moai-adk 0.8.3__py3-none-any.whl → 0.9.0__py3-none-any.whl

moai_adk/templates/.claude/hooks/alfred/shared/core/project.py

@@ -16,6 +16,58 @@ from typing import Any
 CACHE_DIR_NAME = ".moai/cache"
 
 
+def find_project_root(start_path: str | Path = ".") -> Path:
+    """Find MoAI-ADK project root by searching upward for .moai/config.json
+
+    Traverses up the directory tree until it finds .moai/config.json or CLAUDE.md,
+    which indicates the project root. This ensures cache and other files are
+    always created in the correct location, regardless of where hooks execute.
+
+    Args:
+        start_path: Starting directory (default: current directory)
+
+    Returns:
+        Project root Path. If not found, returns start_path as absolute path.
+
+    Examples:
+        >>> find_project_root(".")
+        Path("/Users/user/my-project")
+        >>> find_project_root(".claude/hooks/alfred")
+        Path("/Users/user/my-project")  # Found root 3 levels up
+
+    Notes:
+        - Searches for .moai/config.json first (most reliable)
+        - Falls back to CLAUDE.md if config.json not found
+        - Max depth: 10 levels up (prevent infinite loop)
+        - Returns absolute path for consistency
+
+    TDD History:
+        - RED: 4 test scenarios (root, nested, not found, symlinks)
+        - GREEN: Minimal upward search with .moai/config.json detection
+        - REFACTOR: Add CLAUDE.md fallback, max depth limit, absolute path return
+    """
+    current = Path(start_path).resolve()
+    max_depth = 10  # Prevent infinite loop
+
+    for _ in range(max_depth):
+        # Check for .moai/config.json (primary indicator)
+        if (current / ".moai" / "config.json").exists():
+            return current
+
+        # Check for CLAUDE.md (secondary indicator)
+        if (current / "CLAUDE.md").exists():
+            return current
+
+        # Move up one level
+        parent = current.parent
+        if parent == current:  # Reached filesystem root
+            break
+        current = parent
+
+    # Not found - return start_path as absolute
+    return Path(start_path).resolve()
+
+
 class TimeoutError(Exception):
     """Signal-based timeout exception"""
     pass
@@ -246,7 +298,7 @@ def count_specs(cwd: str) -> dict[str, int]:
     Counts the number of SPECs with status: completed.
 
     Args:
-        cwd: Project root directory path
+        cwd: Project root directory path (or any subdirectory, will search upward)
 
     Returns:
         SPEC progress dictionary. Includes the following keys:
@@ -264,15 +316,19 @@ def count_specs(cwd: str) -> dict[str, int]:
 
     Notes:
         - SPEC File Location: .moai/specs/SPEC-{ID}/spec.md
-        - Completion condition: Include “status: completed” in YAML front matter
+        - Completion condition: Include "status: completed" in YAML front matter
         - If parsing fails, the SPEC is considered incomplete.
+        - Automatically finds project root to locate .moai/specs/
 
     TDD History:
         - RED: 5 items scenario test (0/0, 2/5, 5/5, no directory, parsing error)
         - GREEN: SPEC search with Path.iterdir(), YAML parsing implementation
         - REFACTOR: Strengthened exception handling, improved percentage calculation safety
+        - UPDATE: Add project root detection for consistent path resolution
     """
-    specs_dir = Path(cwd) / ".moai" / "specs"
+    # Find project root to ensure we read specs from correct location
+    project_root = find_project_root(cwd)
+    specs_dir = project_root / ".moai" / "specs"
 
     if not specs_dir.exists():
         return {"completed": 0, "total": 0, "percentage": 0}
@@ -316,7 +372,7 @@ def get_project_language(cwd: str) -> str:
     """Determine the primary project language (prefers config.json).
 
     Args:
-        cwd: Project root directory.
+        cwd: Project root directory (or any subdirectory, will search upward).
 
     Returns:
         Language string in lower-case.
@@ -324,8 +380,11 @@ def get_project_language(cwd: str) -> str:
     Notes:
         - Reads ``.moai/config.json`` first for a quick answer.
         - Falls back to ``detect_language`` if configuration is missing.
+        - Automatically finds project root to locate .moai/config.json
     """
-    config_path = Path(cwd) / ".moai" / "config.json"
+    # Find project root to ensure we read config from correct location
+    project_root = find_project_root(cwd)
+    config_path = project_root / ".moai" / "config.json"
     if config_path.exists():
         try:
             config = json.loads(config_path.read_text())
@@ -336,8 +395,8 @@ def get_project_language(cwd: str) -> str:
             # Fall back to detection on parse errors
             pass
 
-    # Fall back to the original language detection routine
-    return detect_language(cwd)
+    # Fall back to the original language detection routine (use project root)
+    return detect_language(str(project_root))
 
 
 # @CODE:CONFIG-INTEGRATION-001
@@ -382,7 +441,9 @@ def get_version_check_config(cwd: str) -> dict[str, Any]:
         "cache_ttl_hours": 24
     }
 
-    config_path = Path(cwd) / ".moai" / "config.json"
+    # Find project root to ensure we read config from correct location
+    project_root = find_project_root(cwd)
+    config_path = project_root / ".moai" / "config.json"
     if not config_path.exists():
         return defaults
 
@@ -560,8 +621,13 @@ def get_package_version_info(cwd: str = ".") -> dict[str, Any]:
         # Graceful degradation: skip caching on import errors
         VersionCache = None
 
-    # 1. Initialize cache (skip if VersionCache couldn't be imported)
-    cache_dir = Path(cwd) / CACHE_DIR_NAME
+    # 1. Find project root (ensure cache is always in correct location)
+    # This prevents creating .moai/cache in wrong locations when hooks run
+    # from subdirectories like .claude/hooks/alfred/
+    project_root = find_project_root(cwd)
+
+    # 2. Initialize cache (skip if VersionCache couldn't be imported)
+    cache_dir = project_root / CACHE_DIR_NAME
     version_cache = VersionCache(cache_dir) if VersionCache else None
 
     # 2. Get current installed version first (needed for cache validation)
@@ -672,6 +738,7 @@ def get_package_version_info(cwd: str = ".") -> dict[str, Any]:
 
 
 __all__ = [
+    "find_project_root",
     "detect_language",
     "get_git_info",
     "count_specs",

moai_adk/templates/.moai/memory/gitflow-protection-policy.md

@@ -1,36 +1,40 @@
-# GitFlow Advisory Policy
+# GitFlow Protection Policy
 
-**Document ID**: @DOC:GITFLOW-POLICY-001  
-**Published**: 2025-10-17  
-**Status**: Advisory (recommended, not enforced)  
+**Document ID**: @DOC:GITFLOW-POLICY-ALIAS
+**Published**: 2025-10-17
+**Updated**: 2025-10-29
+**Status**: **Enforced via GitHub Branch Protection** (v0.8.3+)
 **Scope**: Personal and Team modes
 
 ---
 
 ## Overview
 
-MoAI-ADK **recommends** a GitFlow-inspired workflow. This policy shares best practices while letting teams adapt them as needed.
+MoAI-ADK **enforces** a GitFlow-inspired workflow through GitHub Branch Protection. As of v0.8.3, the `main` branch is protected and requires Pull Requests for all changes, including from administrators.
 
-## Key Recommendations
+**What Changed**: Previously (v0.3.5-v0.8.2), we used an advisory approach with warnings. Now we enforce proper GitFlow to ensure code quality and prevent accidental direct pushes to main.
 
-### 1. Main Branch Access (Recommended)
+## Key Requirements (Enforced)
 
-| Recommendation | Summary | Enforcement |
-|----------------|---------|-------------|
-| **Merge via develop** | Prefer merging `develop` into `main` | Advisory ⚠️ |
-| **Feature branches off develop** | Branch from `develop` and raise PRs back to `develop` | Advisory ⚠️ |
-| **Release process** | Release flow: `develop` → `main` (release engineer encouraged) | Advisory ⚠️ |
-| **Force push** | Warn when force-pushing, but allow it | Warning ⚠️ |
-| **Direct push** | Warn on direct pushes to `main`, but allow them | Warning ⚠️ |
+### 1. Main Branch Access (Enforced)
 
-### 2. Git Workflow (Recommended)
+| Requirement | Summary | Enforcement |
+|-------------|---------|-------------|
+| **Merge via develop** | MUST merge `develop` into `main` | ✅ Enforced |
+| **Feature branches off develop** | MUST branch from `develop` and raise PRs back to `develop` | ✅ Enforced |
+| **Release process** | Release flow: `develop` → `main` (PR required) | ✅ Enforced |
+| **Force push** | Blocked on `main` | ✅ Blocked |
+| **Direct push** | Blocked on `main` (PR required) | ✅ Blocked |
+
+### 2. Git Workflow (Required)
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│                RECOMMENDED GITFLOW                      │
+│                ENFORCED GITFLOW                         │
+│         (GitHub Branch Protection Active)               │
 └─────────────────────────────────────────────────────────┘
 
-        develop (recommended base branch)
+        develop (required base branch)
           ↑     ↓
     ┌─────────────────┐
     │                 │
@@ -46,13 +50,15 @@ feature/SPEC-{ID}   [PR: feature -> develop]
          │   (release manager prepares)
          ↓
     [PR: develop -> main]
+    [Code review + approval REQUIRED]
+    [All discussions resolved]
     [CI/CD validation]
     [tag creation]
          ↓
-       main (release)
+       main (protected release)
 ```
 
-**Flexibility**: Direct pushes to `main` are still possible, but the workflow above is preferred.
+**Enforcement**: Direct pushes to `main` are **blocked** via GitHub Branch Protection. All changes must go through Pull Requests.
 
 ## Technical Implementation
 
@@ -156,18 +162,29 @@ git push origin v1.0.0
 
 ## Policy Modes
 
-### Strict Mode (Legacy, Currently Disabled)
+### Strict Mode (Active, v0.8.3+) ✅ ENFORCED
+
+**GitHub Branch Protection Enabled**:
+- ✅ **enforce_admins: true** - Administrators must follow all rules
+- ✅ **required_pull_request_reviews** - 1 approval required
+- ✅ **required_conversation_resolution** - All discussions must be resolved
+- ✅ **Block direct pushes to `main`** - PR required for all users
+- ✅ **Block force pushes** - Prevents history rewriting
+- ✅ **Block branch deletion** - Protects main from accidental deletion
 
-- ❌ Block direct pushes to `main`
-- ❌ Block force pushes
-- ❌ Block merges into `main` from any branch other than `develop`
+**What This Means**:
+- ❌ No one (including admins) can push directly to `main`
+- ✅ All changes must go through Pull Requests
+- ✅ PRs require code review approval
+- ✅ All code discussions must be resolved before merge
+- ✅ Enforces proper GitFlow: feature → develop → main
 
-### Advisory Mode (Active, v0.3.5+)
+### Advisory Mode (Legacy, v0.3.5 - v0.8.2)
 
-- ⚠️ Warn but allow direct pushes to `main`
-- ⚠️ Warn but allow force pushes
-- ⚠️ Recommend best practices while preserving flexibility
-- ✅ Respect user judgment
+- ⚠️ Warned but allowed direct pushes to `main`
+- ⚠️ Warned but allowed force pushes
+- ⚠️ Recommended best practices while preserving flexibility
+- ❌ **Deprecated** - Replaced by Strict Mode for better quality control
 
 ---
 
@@ -202,8 +219,98 @@ A: Yes. Expect an advisory warning, yet the push continues.
 **Q: Can I disable the hook entirely?**  
 A: Yes. Remove `.git/hooks/pre-push` or strip its execute permission.
 
-**Q: Why switch to Advisory Mode?**  
-A: To promote best practices while respecting contributor flexibility and judgment.
+**Q: Why switch to Advisory Mode?**
+A: Advisory Mode was used in v0.3.5-v0.8.2. As of v0.8.3, we've switched to Strict Mode with GitHub Branch Protection for better quality control.
+
+**Q: What if develop falls behind main?**
+A: This can happen when hotfixes or releases go directly to main. Regularly sync main → develop to prevent divergence. See "Maintaining develop-main Sync" section below.
+
+**Q: Can I bypass branch protection in emergencies?**
+A: No. Even administrators must follow the PR process. For true emergencies, temporarily disable protection via GitHub Settings (requires admin access), but re-enable immediately after.
+
+---
+
+## Maintaining develop-main Sync
+
+### ⚠️ Critical Rule: develop Must Stay Current
+
+**Problem**: When main receives direct commits (hotfixes, emergency releases) without syncing back to develop, GitFlow breaks:
+
+```
+❌ BAD STATE:
+develop: 3 commits ahead, 29 commits behind main
+- develop has outdated dependencies
+- New features branch from old code
+- Merge conflicts multiply over time
+```
+
+### Signs of Drift
+
+Monitor for these warnings:
+- `git status` shows "Your branch is X commits behind main"
+- Feature branches conflict with main during PR
+- CI/CD failures due to dependency mismatches
+- Version numbers in develop don't match main
+
+### Recovery Procedure
+
+When develop falls behind main:
+
+1. **Assess the Gap**
+   ```bash
+   git log --oneline develop..main  # Commits in main but not develop
+   git log --oneline main..develop  # Commits in develop but not main
+   ```
+
+2. **Sync Strategy: Merge main into develop (Recommended)**
+   ```bash
+   git checkout develop
+   git pull origin develop        # Get latest develop
+   git merge main                 # Merge main into develop
+   # Resolve conflicts if any (prefer main for version/config files)
+   git push origin develop
+   ```
+
+3. **Emergency Only: Reset develop to main (Destructive)**
+   ```bash
+   # ⚠️ ONLY if develop's unique commits are unwanted
+   git checkout develop
+   git reset --hard main
+   git push origin develop --force
+   ```
+
+### Prevention: Regular Sync Schedule
+
+**After every main release** (REQUIRED):
+```bash
+# Immediately after merging develop → main:
+git checkout develop
+git merge main
+git push origin develop
+```
+
+**Weekly maintenance** (for active projects):
+```bash
+# Every Monday morning:
+git checkout develop
+git pull origin main
+git push origin develop
+```
+
+### Real-World Case Study (2025-10-29)
+
+**Situation**: develop was 29 commits behind main due to:
+- v0.8.2, v0.8.3 released directly to main
+- No reverse sync to develop
+- Feature branches contained outdated code
+
+**Resolution**:
+- Merged main → develop (14 file conflicts)
+- Resolved conflicts prioritizing main's versions
+- TAG validation bypassed for merge commit
+- Enabled Strict Mode to prevent future direct pushes
+
+**Lesson**: With Strict Mode active, this won't happen again. All releases must go through develop → main PR flow.
 
 ---
 
@@ -213,6 +320,9 @@ A: To promote best practices while respecting contributor flexibility and judgme
 |------|------|--------|
 | 2025-10-17 | Initial policy drafted (Strict Mode)             | git-manager  |
 | 2025-10-17 | Switched to Advisory Mode (warnings only)        | git-manager  |
+| 2025-10-29 | **Enabled GitHub Branch Protection (Strict Mode)** | Alfred       |
+| 2025-10-29 | Added develop-main sync guidelines and real-world case study | Alfred       |
+| 2025-10-29 | Enforced `enforce_admins`, `required_conversation_resolution` | Alfred       |
 
 ---
 

moai_adk/templates/README.md

@@ -0,0 +1,256 @@
+# MoAI-ADK Project Templates
+
+This directory contains template files that are copied to new projects when users run `moai-adk init`.
+
+## Directory Structure
+
+```
+templates/
+├── .claude/              # Claude Code configuration
+│   ├── agents/          # Alfred sub-agents (12 specialists)
+│   ├── commands/        # Slash commands (/alfred:0-4)
+│   ├── skills/          # 55 reusable knowledge capsules
+│   └── hooks/           # Session lifecycle hooks
+├── .moai/               # MoAI-ADK configuration
+│   ├── config.json     # Project settings (language, mode, owner)
+│   ├── docs/           # Internal documentation
+│   ├── memory/         # Session context persistence
+│   ├── reports/        # Quality and sync reports
+│   └── specs/          # SPEC documents directory
+├── .github/             # GitHub Actions workflows
+│   └── workflows/      # CI/CD automation
+├── CLAUDE.md            # Project guidance for Claude Code
+└── .gitignore          # Git ignore patterns
+```
+
+---
+
+## Template Components
+
+### 1. `.claude/` - Claude Code Configuration (2.0 MB)
+
+The complete Alfred SuperAgent system:
+
+- **Agents** (12 specialists): spec-builder, tdd-implementer, doc-syncer, tag-agent, trust-checker, debug-helper, implementation-planner, project-manager, quality-gate, git-manager, cc-manager, skill-factory
+- **Commands** (4 workflow commands): `/alfred:0-project`, `/alfred:1-plan`, `/alfred:2-run`, `/alfred:3-sync`
+- **Skills** (55 knowledge capsules): Foundation (5), Essentials (4), Alfred (7), Domain (7), Language (18), CC (14)
+- **Hooks**: SessionStart, PreToolUse, PostToolUse lifecycle guards
+
+### 2. `.moai/` - MoAI-ADK Configuration (120 KB)
+
+Project configuration and memory:
+
+- **config.json**: Language settings, project owner, team mode
+- **memory/**: Persistent session context and state
+- **docs/**: Internal guides and strategies
+- **reports/**: Sync analysis and quality reports
+- **specs/**: SPEC document directory structure
+
+### 3. `.github/` - GitHub Workflows (80 KB)
+
+Continuous integration and deployment:
+
+- **workflows/**: Pre-configured GitHub Actions for testing, linting, type checking
+- **ISSUE_TEMPLATE/**: Standard issue templates
+
+### 4. `CLAUDE.md` - Project Guidance (15 KB)
+
+The master instruction document for Claude Code:
+
+- **Variable substitution**: `{{PROJECT_OWNER}}`, `{{CONVERSATION_LANGUAGE}}`, `{{CODEBASE_LANGUAGE}}`
+- **Customizable**: User-facing project instructions in user's language
+
+---
+
+## How Templates Are Used
+
+### Initialization Flow
+
+When a user runs `moai-adk init`, the `TemplateProcessor` class performs:
+
+1. **Template Discovery**: Locates `src/moai_adk/templates/` via package path resolution
+2. **Directory Copy**: Copies `.claude/`, `.moai/`, `.github/` to target project
+3. **File Copy**: Copies `CLAUDE.md`, `.gitignore` individually
+4. **Variable Substitution**: Replaces template placeholders with user values:
+   - `{{PROJECT_OWNER}}` → User's configured name
+   - `{{CONVERSATION_LANGUAGE}}` → User's language (Korean, Japanese, etc.)
+   - `{{CONVERSATION_LANGUAGE_NAME}}` → Language display name
+   - `{{CODEBASE_LANGUAGE}}` → Detected or specified project language
+
+### Current Template Processor Logic
+
+**File**: `src/moai_adk/core/template/processor.py`
+
+**Methods**:
+- `_copy_claude()`: Copy Alfred system (agents, commands, skills, hooks)
+- `_copy_moai()`: Copy MoAI-ADK configuration and structure
+- `_copy_github()`: Copy GitHub Actions workflows
+- `_copy_claude_md()`: Copy and substitute variables in CLAUDE.md
+- `_copy_gitignore()`: Copy Git ignore patterns
+
+---
+
+## @TAG System & Traceability
+
+### What Are @TAG Markers?
+
+**@TAG markers** are MoAI-ADK's core traceability feature, linking:
+- `@SPEC:ID` → Requirements
+- `@TEST:ID` → Test cases
+- `@CODE:ID` → Implementation
+- `@DOC:ID` → Documentation
+
+**Example**:
+```python
+# @CODE:AUTH-001 | SPEC: SPEC-AUTH-001/spec.md | Chain: AUTH-001
+def authenticate_user(username, password):
+    """Authenticate user credentials (SPEC-AUTH-001)."""
+    # Implementation...
+```
+
+### How @TAGs Work in New Projects
+
+**Day 1**: Your project starts with **0 @TAGs**
+- No setup required, no validation needed
+- Tags are created automatically via Alfred commands
+
+**Day 30**: Tags grow naturally
+- `/alfred:1-plan "User auth"` → creates `@SPEC:AUTH-001`
+- `/alfred:2-run SPEC-AUTH-001` → creates `@TEST:AUTH-001`, `@CODE:AUTH-001`
+- `/alfred:3-sync` → creates `@DOC:AUTH-001`
+
+**Simple & Automatic**: @TAGs are added by Alfred agents, not by you.
+
+### TAG Validation (Advanced, Optional)
+
+**MoAI-ADK framework** uses TAG validation (82 files, complex chains)
+**Your new project** does NOT need TAG validation
+
+**When you might want TAG validation**:
+- Project has 100+ TAGs
+- Team has 10+ developers
+- Need automated quality gates
+
+**How to add TAG validation** (if needed):
+- See MoAI-ADK documentation: "Advanced: TAG Validation Setup"
+- Manual installation from framework source
+- Optional plugin (future): `moai-adk plugin install tag-validation`
+
+---
+
+## Maintenance Guidelines
+
+### Syncing Skills to Templates
+
+**Script**: `scripts/sync_allowed_tools.py` (Korean)
+
+This script synchronizes `.claude/skills/` to `src/moai_adk/templates/.claude/skills/` to ensure new projects receive the latest skill versions.
+
+**When to run**:
+- After adding new skills
+- After updating existing skill content
+- Before releasing a new version
+
+### Template Versioning
+
+Templates are versioned with the MoAI-ADK package. When releasing:
+
+1. Update template files in `src/moai_adk/templates/`
+2. Run skill sync script
+3. Update this README if structure changes
+4. Test with `moai-adk init` on a clean directory
+5. Document breaking changes in CHANGELOG.md
+
+### Testing Template Changes
+
+**Integration tests**: `tests/integration/test_phase_executor.py`
+
+```bash
+# Test project initialization
+pytest tests/integration/test_phase_executor.py::test_phase_0_initialization
+
+# Test full workflow
+pytest tests/e2e/test_e2e_workflow.py
+```
+
+---
+
+## Related Documentation
+
+- **CLAUDE.md**: Main project guidance (repository root)
+- **CLAUDE-AGENTS-GUIDE.md**: Alfred team structure (repository root)
+- **CLAUDE-RULES.md**: Development rules and conventions (repository root)
+- **Language Configuration**: `.moai/memory/language-config-schema.md`
+
+---
+
+## FAQ
+
+### Q: What is the difference between MoAI-ADK framework and user projects?
+
+**A**:
+- **MoAI-ADK framework** = The tool itself (this repository, needs complex validation)
+- **User projects** = Projects created by `moai-adk init` (your apps, simple start)
+
+Think of it like Ruby on Rails:
+- Rails framework has complex CI/CD infrastructure
+- `rails new my-app` creates a simple, clean project
+
+### Q: Will my project have @TAG markers?
+
+**A**: Yes! @TAG markers are **automatic and core** to MoAI-ADK workflow:
+- Created automatically by `/alfred:1-plan`, `/alfred:2-run`, `/alfred:3-sync`
+- Provide traceability (link requirements → tests → code → docs)
+- No validation needed for small/medium projects (simple grep is enough)
+
+### Q: When do I need TAG validation?
+
+**A**: Only for **mature, large-scale projects**:
+- 100+ SPEC documents
+- 10+ team members
+- Complex TAG chains requiring automated integrity checks
+
+For most projects, @TAG markers alone are sufficient.
+
+### Q: Will old projects break when templates are updated?
+
+**A**: No. Templates only affect **new** projects created via `moai-adk init`. Existing projects are not modified unless explicitly updated via `moai-adk update`.
+
+### Q: How do I customize templates for my organization?
+
+**A**: Fork MoAI-ADK and modify files in `src/moai_adk/templates/`. Maintain your fork's template sync script to merge upstream updates.
+
+---
+
+## Design Philosophy
+
+### Framework vs User Projects
+
+**What MoAI-ADK framework needs** (this repository):
+- ✅ Complex TAG validation (82 files, orphan/duplicate detection)
+- ✅ Advanced CI/CD workflows
+- ✅ Quality gates for framework development
+
+**What new user projects need** (`moai-adk init`):
+- ✅ Alfred SuperAgent (workflow orchestration)
+- ✅ @TAG markers (traceability)
+- ✅ Basic CI/CD (testing, linting)
+- ❌ NO complex TAG validation (not needed until project matures)
+
+**Goal**: Start simple, grow as needed.
+
+---
+
+## Change History
+
+| Date | Version | Changes |
+|------|---------|---------|
+| 2025-10-29 | 0.8.3 | Removed TAG validation system from templates (design clarification) |
+| 2025-10-29 | 0.7.0 | Language localization complete (5 languages supported) |
+| 2025-10-16 | 0.6.0 | Initial template structure with Alfred system |
+
+---
+
+**Last Updated**: 2025-10-29
+**Maintained By**: MoAI-ADK Core Team
+**Design Principle**: Start simple, scale as needed