Agent skill

scope-appropriate-architecture

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.

View SKILL.md on GitHub Repository
Stars 143
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/yonatangross/orchestkit/tree/main/src/skills/scope-appropriate-architecture

Metadata

Additional technical details for this skill

category
architecture

SKILL.md

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

yonatangross/orchestkit

expect

Diff-aware AI browser testing — analyzes git changes, generates targeted test plans, and executes them via agent-browser. Reads git diff to determine what changed, maps changes to affected pages via route map, generates a test plan scoped to the diff, and runs it with pass/fail reporting. Use when testing UI changes, verifying PRs before merge, running regression checks on changed components, or validating that recent code changes don't break the user-facing experience.

143 15
Explore
yonatangross/orchestkit

github-operations

GitHub CLI operations for issues, PRs, milestones, and Projects v2. Covers gh commands, REST API patterns, and automation scripts. Use when managing GitHub issues, PRs, milestones, or Projects with gh.

143 15
Explore
yonatangross/orchestkit

chain-patterns

Chain patterns for CC 2.1.71 pipelines — MCP detection, handoff files, checkpoint-resume, worktree agents, CronCreate monitoring. Use when building multi-phase pipeline skills. Loaded via skills: field by pipeline skills (fix-issue, implement, brainstorm, verify). Not user-invocable.

143 15
Explore
yonatangross/orchestkit

storybook-mcp-integration

Storybook MCP server integration for component-aware AI development. Covers 6 tools across 3 toolsets (dev, docs, testing): component discovery via list-all-documentation/get-documentation, story previews via preview-stories, and automated testing via run-story-tests. Use when generating components that should reuse existing Storybook components, running component tests via MCP, or previewing stories in chat.

143 15
Explore
yonatangross/orchestkit

component-search

Search 21st.dev component registry for production-ready React components. Finds components by natural language description, filters by framework and style system, returns ranked results with install instructions. Use when looking for UI components, finding alternatives to existing components, or sourcing design system building blocks.

143 15
Explore
yonatangross/orchestkit

ai-ui-generation

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

143 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results