scope-appropriate-architecture
$
npx mdskill add yonatangross/orchestkit/scope-appropriate-architectureClassifies projects into six tiers to constrain architectural patterns and prevent over-engineering.
- Helps right-size architecture decisions based on project scope and complexity.
- Integrates with tools like Read, Glob, Grep, WebFetch, and WebSearch for analysis.
- Decides recommendations by detecting the project tier first and limiting pattern choices accordingly.
- Presents results through guidance on appropriate architecture, database, authentication, and testing for each tier.
SKILL.md
.github/skills/scope-appropriate-architectureView on GitHub ↗
---
name: scope-appropriate-architecture
license: MIT
compatibility: "Claude Code 2.1.76+"
description: "Right-sizes architecture to project scope. Prevents over-engineering by classifying projects into 6 tiers and constraining pattern choices accordingly. Use when designing architecture, selecting patterns, or when brainstorm/implement detect a project tier."
tags: [architecture, yagni, over-engineering, scope, patterns]
version: 1.0.0
author: OrchestKit
user-invocable: false
disable-model-invocation: true
context: inherit
complexity: low
persuasion-type: guidance
effort: low
model: haiku
metadata:
category: architecture
allowed-tools:
- Read
- Glob
- Grep
- WebFetch
- WebSearch
---
# Scope-Appropriate Architecture
Right-size every architectural decision to the project's actual needs. Not every project needs hexagonal architecture, CQRS, or microservices.
**Core principle:** Detect the project tier first, then constrain all downstream pattern choices to that tier's complexity ceiling.
---
## The 6 Project Tiers
| Tier | LOC Ratio | Architecture | DB | Auth | Tests |
|------|-----------|-------------|-----|------|-------|
| **1. Interview/Take-home** | 1.0-1.3x | Flat files, no layers | SQLite / JSON | None or basic | 8-15 focused |
| **2. Hackathon/Prototype** | 0.8-1.0x | Single file if possible | SQLite / in-memory | None | Zero |
| **3. Startup/MVP** | 1.0-1.5x | MVC monolith | Managed Postgres | Clerk/Supabase Auth | Happy path + critical |
| **4. Growth-stage** | 1.5-2.0x | Modular monolith | Postgres + Redis | Auth service | Unit + integration |
| **5. Enterprise** | 2.0-3.0x | Hexagonal/DDD | Postgres + queues | OAuth2/SAML | Full pyramid |
| **6. Open Source** | 1.2-1.8x | Minimal API surface | Configurable | Optional | Exhaustive public API |
**LOC Ratio** = total lines / core business logic lines. Higher ratio = more infrastructure code relative to business value.
---
## Auto-Detection Signals
| Signal | Tier Indicator |
|--------|---------------|
| README contains "take-home", "assignment", "interview" | Tier 1 |
| Time limit mentioned (e.g., "4 hours", "weekend") | Tier 1-2 |
| < 10 files, no CI, no Docker | Tier 1-2 |
| `.github/workflows/` present | Tier 3+ |
| `package.json` with 20+ dependencies | Tier 3+ |
| Kubernetes/Terraform files present | Tier 4-5 |
| `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` | Tier 6 |
| Monorepo with `packages/` or `apps/` | Tier 4-5 |
**When confidence is low:** Ask the user with `AskUserQuestion`.
---
## Pattern Appropriateness Matrix
| Pattern | Interview | Hackathon | MVP | Growth | Enterprise |
|---------|-----------|-----------|-----|--------|------------|
| Repository pattern | OVERKILL | OVERKILL | BORDERLINE | APPROPRIATE | REQUIRED |
| Event-driven arch | OVERKILL | OVERKILL | OVERKILL | SELECTIVE | APPROPRIATE |
| DI containers | OVERKILL | OVERKILL | LIGHT ONLY | APPROPRIATE | REQUIRED |
| Separate DTO layers | OVERKILL | OVERKILL | 1 EXTRA | 2 LAYERS | ALL LAYERS |
| Microservices | NEVER | NEVER | NEVER | EXTRACT ONLY | APPROPRIATE |
| CQRS | OVERKILL | OVERKILL | OVERKILL | OVERKILL | WHEN JUSTIFIED |
| Hexagonal architecture | OVERKILL | OVERKILL | OVERKILL | BORDERLINE | APPROPRIATE |
| DDD (bounded contexts) | OVERKILL | OVERKILL | OVERKILL | SELECTIVE | APPROPRIATE |
| Message queues | OVERKILL | OVERKILL | BORDERLINE | APPROPRIATE | REQUIRED |
| API versioning | SKIP | SKIP | URL prefix | Header-based | Full strategy |
| Error handling | try/catch | console.log | Error boundary | Error service | RFC 9457 |
| Logging | console.log | none | Structured JSON | Centralized | OpenTelemetry |
**Rule of thumb:** If a pattern shows OVERKILL for the detected tier, do NOT use it. Suggest the simpler alternative instead.
---
## Technology Quick-Reference by Tier
| Choice | Interview | Hackathon | MVP | Growth | Enterprise |
|--------|-----------|-----------|-----|--------|------------|
| **Database** | SQLite / JSON file | In-memory / SQLite | Managed Postgres | Postgres + Redis | Postgres + queues + cache |
| **Auth** | Hardcoded / none | None | Clerk / Supabase Auth | Auth service | OAuth2 / SAML / SSO |
| **State mgmt** | useState | useState | Zustand / Context | Zustand + React Query | Redux / custom + cache |
| **CSS** | Inline / Tailwind | Tailwind | Tailwind | Tailwind + design tokens | Design system |
| **API** | Express routes | Single file handler | Next.js API routes | FastAPI / Express | Gateway + services |
| **Deployment** | localhost | Vercel / Railway | Vercel / Railway | Docker + managed | K8s / ECS |
| **CI/CD** | None | None | GitHub Actions basic | Multi-stage pipeline | Full pipeline + gates |
| **Monitoring** | None | None | Error tracking only | APM + logs | Full observability stack |
---
## Build vs Buy Decision Tree (Tiers 1-3)
For Interview, Hackathon, and MVP tiers, **always prefer buying over building**:
| Capability | BUY (use SaaS) | BUILD (only if) |
|-----------|----------------|-----------------|
| Auth | Clerk, Supabase Auth, Auth0 | Core product IS auth |
| Payments | Stripe | Core product IS payments |
| Email | Resend, SendGrid | Core product IS email |
| File storage | S3, Cloudflare R2 | Compliance requires on-prem |
| Search | Algolia, Typesense Cloud | > 10M docs or custom ranking |
| Analytics | PostHog, Mixpanel | Unique data requirements |
**Time savings:** Auth alone is 2-4 weeks build vs 2 hours integrate.
---
## Upgrade Path
When a project grows beyond its current tier, upgrade incrementally:
```
Tier 2 (Prototype) → Tier 3 (MVP)
Add: Postgres, basic auth, error boundaries, CI
Tier 3 (MVP) → Tier 4 (Growth)
Add: Redis cache, background jobs, monitoring, module boundaries
Tier 4 (Growth) → Tier 5 (Enterprise)
Add: DI, bounded contexts, message queues, full observability
Extract: First microservice (only the proven bottleneck)
```
**Key insight:** You can always add complexity later. You cannot easily remove it.
---
## When This Skill Activates
This skill is loaded by:
- `brainstorm` Phase 0 (context discovery)
- `implement` Step 0 (context discovery)
- `quality-gates` YAGNI check
- Any skill that needs to right-size a recommendation
The detected tier is passed as context to constrain downstream decisions.
---
## Related Skills
- `ork:brainstorm` - Uses tier detection in Phase 0 to constrain ideas
- `ork:implement` - Uses tier detection in Step 0 to constrain architecture
- `ork:quality-gates` - YAGNI gate references this skill's tier matrix
- `ork:architecture-patterns` - Architecture validation (constrained by tier)
---
## References
Load on demand with `Read("${CLAUDE_SKILL_DIR}/references/<file>")`:
| File | Content |
|------|---------|
| `interview-takehome.md` | Tiers 1-2 in detail |
| `startup-mvp.md` | Tier 3 patterns and decisions |
| `enterprise.md` | Tiers 4-5 patterns and justification criteria |
| `open-source.md` | Tier 6 unique considerations |
More from yonatangross/orchestkit
- agent-orchestrationAgent orchestration patterns for agentic loops, multi-agent coordination, alternative frameworks, and multi-scenario workflows. Use when building autonomous agent loops, coordinating multiple agents, evaluating CrewAI/AutoGen/Swarm, or orchestrating complex multi-step scenarios.
- ai-ui-generationAI-assisted UI generation patterns for json-render, v0, Bolt, and Cursor workflows. Covers prompt engineering for component generation, review checklists for AI-generated code, design token injection, refactoring for design system conformance, and CI gates for quality assurance. Use when generating UI components with AI tools, rendering multi-surface MCP visual output, reviewing AI-generated code, or integrating AI output into design systems.
- analyticsQuery cross-project usage analytics. Use when reviewing agent, skill, hook, or team performance across OrchestKit projects. Also replay sessions, estimate costs, and view model delegation trends.
- animation-motion-designAnimation and motion design patterns using Motion library (formerly Framer Motion) and View Transitions API. Use when implementing component animations, page transitions, micro-interactions, gesture-driven UIs, or ensuring motion accessibility with prefers-reduced-motion.
- architecture-patternsArchitecture validation and patterns for clean architecture, backend structure enforcement, project structure validation, test standards, and context-aware sizing. Use when designing system boundaries, enforcing layered architecture, validating project structure, defining test standards, or choosing the right architecture tier for project scope.
- ascii-visualizerASCII diagram patterns for architecture, workflows, file trees, and data visualizations. Use when creating terminal-rendered diagrams, box-drawing layouts, progress bars, swimlanes, or blast radius visualizations.
- assessAssesses and rates quality 0-10 with pros/cons analysis. Use when evaluating code, designs, or approaches.
- async-jobsAsync job processing patterns for background tasks, Celery workflows, task scheduling, retry strategies, and distributed task execution. Use when implementing background job processing, task queues, or scheduled task systems.
- audit-fullFull-codebase audit using 1M context window. Security, architecture, and dependency analysis in a single pass. Use when you need whole-project analysis.
- audit-skillsAudits all OrchestKit skills for quality, completeness, and compliance with authoring standards. Use when checking skill health, before releases, or after bulk skill edits to surface SKILL.md files that are too long, have missing frontmatter, lack rules/references, or are unregistered in manifests.