moai-adk 0.35.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-foundation-core/examples.md

@@ -0,0 +1,358 @@
+# MoAI Foundation Core Examples
+
+실용적인 예시를 통해 MoAI Foundation Core의 6가지 핵심 원칙을 학습합니다.
+
+---
+
+## Example 1: TRUST 5 Quality Gate 적용
+
+**Scenario**: 새로운 기능을 개발한 후 TRUST 5 품질 게이트를 통과시키는 상황
+
+**Input**:
+```python
+# 개발된 코드에 TRUST 5 검증 요청
+Task(
+    subagent_type="core-quality",
+    prompt="Validate code quality using TRUST 5 framework",
+    context={
+        "target_path": "/src/features/user_auth.py",
+        "validation_level": "strict"
+    }
+)
+```
+
+**Output**:
+```markdown
+TRUST 5 Validation Report
+=========================
+
+Test-first: PASS (87% coverage, threshold: 85%)
+Readable: PASS (naming conventions compliant)
+Unified: PASS (black + isort formatting verified)
+Secured: PASS (no OWASP vulnerabilities detected)
+Trackable: PASS (commit messages follow conventional format)
+
+Overall Status: APPROVED for merge
+```
+
+**Explanation**: TRUST 5의 5가지 품질 기준(Test-first, Readable, Unified, Secured, Trackable)을 자동으로 검증하여 코드 품질을 보장합니다. 85% 이상 테스트 커버리지, 일관된 코드 스타일, 보안 취약점 부재를 확인합니다.
+
+---
+
+## Example 2: SPEC-First TDD 3단계 워크플로우
+
+**Scenario**: 사용자 인증 기능을 SPEC-First TDD 방식으로 개발하는 전체 과정
+
+**Input**:
+```bash
+# Phase 1: SPEC 생성
+/moai:1-plan "JWT 기반 사용자 인증 시스템 구현"
+
+# Phase 2: TDD 실행 (Phase 1 완료 후 /clear 실행)
+/clear
+/moai:2-run SPEC-001
+
+# Phase 3: 문서화
+/moai:3-sync SPEC-001
+```
+
+**Output**:
+```markdown
+Phase 1 Result (.moai/specs/SPEC-001/spec.md):
+==============================================
+ID: SPEC-001
+Title: JWT Authentication System
+EARS Format:
+- [Ubiquitous] System shall hash passwords using bcrypt
+- [Event-driven] When user submits credentials, system shall validate and return JWT
+- [State-driven] While token is valid, user shall access protected resources
+- [Unwanted] System shall not store plain-text passwords
+Token Usage: 28K/30K
+
+Phase 2 Result:
+===============
+RED: 5 failing tests created (test_login, test_register, test_token_validation...)
+GREEN: All tests passing after implementation
+REFACTOR: Code optimized, duplications removed
+Coverage: 92% (threshold: 85%)
+Token Usage: 165K/180K
+
+Phase 3 Result:
+===============
+API Documentation: Generated (docs/api/auth.md)
+Architecture Diagram: Created (docs/diagrams/auth-flow.mermaid)
+Token Usage: 35K/40K
+```
+
+**Explanation**: SPEC-First TDD는 3단계로 진행됩니다. Phase 1에서 EARS 형식으로 요구사항을 정의하고, Phase 2에서 RED-GREEN-REFACTOR 사이클로 구현하며, Phase 3에서 문서를 생성합니다. 각 Phase 사이에 /clear를 실행하여 토큰을 절약합니다.
+
+---
+
+## Example 3: 에이전트 위임 패턴 (복잡한 작업)
+
+**Scenario**: 10개 이상의 파일이 관련된 복잡한 마이크로서비스 개발
+
+**Input**:
+```python
+# 복잡한 작업: 순차 + 병렬 위임 조합
+async def develop_microservice():
+    # Phase 1: 순차 실행 (의존성 있음)
+    design = await Task(
+        subagent_type="api-designer",
+        prompt="Design REST API for order management service"
+    )
+
+    # Phase 2: 병렬 실행 (독립적)
+    backend, frontend, tests = await Promise.all([
+        Task(
+            subagent_type="backend-expert",
+            prompt="Implement API endpoints",
+            context={"design": design}
+        ),
+        Task(
+            subagent_type="frontend-expert",
+            prompt="Create admin dashboard UI",
+            context={"design": design}
+        ),
+        Task(
+            subagent_type="tdd-implementer",
+            prompt="Generate integration tests",
+            context={"design": design}
+        )
+    ])
+
+    # Phase 3: 최종 검증
+    validation = await Task(
+        subagent_type="core-quality",
+        prompt="Validate complete implementation",
+        context={"components": [backend, frontend, tests]}
+    )
+
+    return validation
+```
+
+**Output**:
+```markdown
+Delegation Report
+=================
+
+Phase 1 (Sequential):
+- api-designer: Completed in 45s
+  - 12 endpoints designed
+  - OpenAPI spec generated
+
+Phase 2 (Parallel - 3 agents):
+- backend-expert: Completed in 120s
+  - 8 API handlers implemented
+  - Database models created
+- frontend-expert: Completed in 90s
+  - 6 React components created
+  - Admin dashboard ready
+- tdd-implementer: Completed in 75s
+  - 24 integration tests generated
+  - Mock data prepared
+
+Phase 3 (Validation):
+- core-quality: TRUST 5 PASSED
+  - Coverage: 89%
+  - No security issues
+  - Code style compliant
+
+Total Time: 195s (vs 330s sequential)
+Efficiency Gain: 41%
+```
+
+**Explanation**: 복잡한 작업은 순차/병렬 위임을 조합합니다. 의존성이 있는 작업(API 설계)은 먼저 순차 실행하고, 독립적인 작업(백엔드, 프론트엔드, 테스트)은 병렬로 실행하여 전체 시간을 41% 단축합니다.
+
+---
+
+## Common Patterns
+
+### Pattern 1: Token Budget 관리
+
+토큰 예산을 효율적으로 관리하는 패턴입니다.
+
+```python
+# SPEC Phase: 30K 예산
+Task(subagent_type="workflow-spec", prompt="Create SPEC")
+# → SPEC 완료 후 반드시 /clear 실행 (45-50K 절약)
+
+# TDD Phase: 180K 예산
+Task(subagent_type="tdd-implementer", prompt="Implement with TDD")
+# → 선택적 파일 로딩, 필요한 파일만 로드
+
+# Docs Phase: 40K 예산
+Task(subagent_type="workflow-docs", prompt="Generate documentation")
+# → 결과 캐싱 및 템플릿 재사용
+```
+
+모니터링 방법:
+- /context 명령으로 현재 토큰 사용량 확인
+- 150K 초과 시 /clear 권장
+- 50+ 메시지 후 컨텍스트 초기화 고려
+
+### Pattern 2: Progressive Disclosure 구조
+
+스킬 문서를 3단계로 구조화하는 패턴입니다.
+
+```markdown
+## Quick Reference (30초, ~1000 토큰)
+- 핵심 개념만 포함
+- 즉시 사용 가능한 정보
+
+## Implementation Guide (5분, ~3000 토큰)
+- 단계별 워크플로우
+- 실용적인 예시
+
+## Advanced Patterns (10+분, ~5000 토큰)
+- 심층 기술 정보
+- 엣지 케이스 처리
+```
+
+파일 분리 기준:
+- SKILL.md: 500줄 이하 (핵심 내용)
+- modules/: 상세 내용 (무제한)
+- examples.md: 실행 가능한 예시
+
+### Pattern 3: 조건부 위임 (분석 기반)
+
+문제 유형에 따라 적절한 에이전트를 선택하는 패턴입니다.
+
+```python
+# 먼저 문제 분석
+analysis = await Task(
+    subagent_type="debug-helper",
+    prompt="Analyze the error and classify type"
+)
+
+# 분석 결과에 따라 위임
+if analysis.type == "security":
+    await Task(subagent_type="security-expert", prompt="Fix security issue")
+elif analysis.type == "performance":
+    await Task(subagent_type="performance-expert", prompt="Optimize performance")
+elif analysis.type == "logic":
+    await Task(subagent_type="backend-expert", prompt="Fix business logic")
+else:
+    await Task(subagent_type="debug-expert", prompt="General debugging")
+```
+
+---
+
+## Anti-Patterns (피해야 할 패턴)
+
+### Anti-Pattern 1: 직접 실행
+
+**Problem**: Alfred가 에이전트 위임 없이 직접 코드를 작성하거나 수정함
+
+```python
+# 잘못된 예시
+def alfred_direct_execution():
+    # Alfred가 직접 파일 수정 - 절대 금지!
+    with open("src/app.py", "w") as f:
+        f.write("# Direct modification")
+```
+
+**Solution**: 모든 작업은 전문 에이전트에게 위임
+
+```python
+# 올바른 예시
+await Task(
+    subagent_type="backend-expert",
+    prompt="Modify src/app.py to add new feature",
+    context={"requirements": feature_spec}
+)
+```
+
+### Anti-Pattern 2: Phase 간 /clear 누락
+
+**Problem**: SPEC Phase 완료 후 /clear 없이 TDD Phase 진행하여 토큰 낭비
+
+```bash
+# 잘못된 예시
+/moai:1-plan "feature"  # 30K 사용
+/moai:2-run SPEC-001    # 이전 컨텍스트 유지 → 토큰 부족!
+```
+
+**Solution**: Phase 완료 후 반드시 /clear 실행
+
+```bash
+# 올바른 예시
+/moai:1-plan "feature"  # 30K 사용
+/clear                  # 컨텍스트 초기화 (45-50K 절약)
+/moai:2-run SPEC-001    # 새로운 180K 예산으로 시작
+```
+
+### Anti-Pattern 3: 과도한 순차 실행
+
+**Problem**: 독립적인 작업을 불필요하게 순차 실행
+
+```python
+# 잘못된 예시 - 비효율적
+backend = await Task(subagent_type="backend-expert", ...)
+frontend = await Task(subagent_type="frontend-expert", ...)  # 대기 불필요
+docs = await Task(subagent_type="docs-generator", ...)       # 대기 불필요
+```
+
+**Solution**: 독립적인 작업은 병렬 실행
+
+```python
+# 올바른 예시 - 효율적
+backend, frontend, docs = await Promise.all([
+    Task(subagent_type="backend-expert", ...),
+    Task(subagent_type="frontend-expert", ...),
+    Task(subagent_type="docs-generator", ...)
+])
+```
+
+### Anti-Pattern 4: TRUST 5 검증 생략
+
+**Problem**: 품질 게이트 없이 코드 머지
+
+```bash
+# 잘못된 예시
+git add . && git commit -m "Add feature" && git push
+# → 테스트 커버리지, 보안 취약점 미확인
+```
+
+**Solution**: 머지 전 반드시 TRUST 5 검증
+
+```python
+# 올바른 예시
+validation = await Task(
+    subagent_type="core-quality",
+    prompt="Validate with TRUST 5 before merge"
+)
+
+if validation.passed:
+    # 안전하게 머지
+    await Task(subagent_type="git-manager", prompt="Create PR and merge")
+else:
+    # 이슈 해결 후 재검증
+    await Task(subagent_type="debug-expert", prompt="Fix validation issues")
+```
+
+---
+
+## Quick Decision Matrix
+
+작업 복잡도에 따른 에이전트 선택 가이드:
+
+| 복잡도 | 파일 수 | 에이전트 수 | 실행 패턴 |
+|--------|---------|------------|----------|
+| Simple | 1개 | 1-2개 | 순차 |
+| Medium | 3-5개 | 2-3개 | 순차 |
+| Complex | 10+개 | 5+개 | 순차+병렬 혼합 |
+
+토큰 예산 배분:
+
+| Phase | 예산 | 전략 |
+|-------|------|------|
+| SPEC | 30K | 요구사항만 로드 |
+| TDD | 180K | 선택적 파일 로딩 |
+| Docs | 40K | 결과 캐싱 |
+| Total | 250K | Phase 분리 |
+
+---
+
+Version: 1.0.0
+Last Updated: 2025-12-06

moai_adk/templates/.claude/skills/moai-foundation-core/modules/README.md

@@ -0,0 +1,296 @@
+# MoAI Foundation Core - Modules Directory
+
+Purpose: Extended documentation modules for moai-foundation-core skill, providing deep dives into each foundational principle.
+
+Version: 1.0.0
+Last Updated: 2025-11-25
+
+---
+
+## Module Overview
+
+This directory contains 9 comprehensive modules covering MoAI-ADK's foundational principles and execution rules:
+
+### 1. trust-5-framework.md (982 lines)
+TRUST 5 Quality Framework - Automated quality gates ensuring code quality, security, maintainability, and traceability.
+
+Quick Access:
+- Test-first (≥85% coverage)
+- Readable (≤10 complexity)
+- Unified (consistent patterns)
+- Secured (OWASP compliance)
+- Trackable (clear commits)
+
+Use Cases:
+- Quality gate configuration
+- CI/CD pipeline integration
+- Pre-commit hook setup
+- TRUST 5 validation framework
+
+---
+
+### 2. spec-first-tdd.md (866 lines)
+Specification-Driven Development - EARS format requirements with RED-GREEN-REFACTOR TDD cycles.
+
+Quick Access:
+- SPEC generation (/moai:1-plan)
+- EARS format patterns
+- TDD implementation (/moai:2-run)
+- Documentation sync (/moai:3-sync)
+
+Use Cases:
+- New feature development
+- Requirement specification
+- Test-driven implementation
+- Documentation automation
+
+---
+
+### 3. delegation-patterns.md (757 lines)
+Agent Orchestration - Task delegation strategies for specialized agents without direct execution.
+
+Quick Access:
+- Sequential delegation (dependencies)
+- Parallel delegation (independent tasks)
+- Conditional delegation (analysis-based routing)
+- Context passing optimization
+
+Use Cases:
+- Complex workflow orchestration
+- Multi-agent coordination
+- Error handling and recovery
+- Performance optimization
+
+---
+
+### 4. token-optimization.md (656 lines)
+Budget Management - Efficient 200K token budget through strategic context management.
+
+Quick Access:
+- Phase-based allocation (SPEC 30K | TDD 180K | Docs 40K)
+- /clear execution rules
+- Selective file loading
+- Model selection strategy
+
+Use Cases:
+- Token budget planning
+- Context optimization
+- Cost reduction (60-70% savings)
+- Performance tuning
+
+---
+
+### 5. progressive-disclosure.md (576 lines)
+Content Architecture - Three-tier knowledge delivery balancing value with depth.
+
+Quick Access:
+- Level 1: Quick Reference (30s, 1K tokens)
+- Level 2: Implementation Guide (5min, 3K tokens)
+- Level 3: Advanced Patterns (10+min, 5K tokens)
+- 500-line SKILL.md limit enforcement
+
+Use Cases:
+- Skill content structuring
+- Documentation architecture
+- File splitting strategy
+- Progressive loading
+
+---
+
+### 6. modular-system.md (588 lines)
+File Organization - Scalable file structure for unlimited content depth.
+
+Quick Access:
+- Standard structure (SKILL.md + modules/ + examples.md + reference.md)
+- File splitting strategy
+- Cross-reference patterns
+- Module discovery
+
+Use Cases:
+- Skill organization
+- File structure validation
+- Automated splitting
+- Navigation generation
+
+---
+
+### 7. agents-reference.md (NEW)
+Agent Catalog - Complete reference of MoAI-ADK's 26 specialized agents with 7-tier hierarchy.
+
+Quick Access:
+- `{domain}-{role}` naming convention
+- 7 tiers: workflow, core, domain, mcp, factory, support, ai
+- Agent selection criteria
+- MCP Resume pattern (40-60% token savings)
+
+Use Cases:
+- Agent selection for Task() delegation
+- Understanding agent hierarchy
+- MCP integrator usage
+- Historical agent merges
+
+---
+
+### 8. commands-reference.md (NEW)
+Command Catalog - Complete reference for MoAI-ADK's 6 core commands in SPEC-First TDD workflow.
+
+Quick Access:
+- /moai:0-project (Project init)
+- /moai:1-plan (SPEC generation)
+- /moai:2-run (TDD implementation)
+- /moai:3-sync (Documentation)
+- /moai:9-feedback (Improvement)
+- /moai:99-release (Deployment)
+
+Use Cases:
+- Command workflow execution
+- /clear execution rules
+- Token budget by command
+- Git integration patterns
+
+---
+
+### 9. execution-rules.md (NEW)
+Security & Constraints - Security policies, execution constraints, and Git workflow strategies.
+
+Quick Access:
+- Agent-First Mandate (Task() only)
+- Security Sandbox (protected paths, forbidden commands)
+- Permission System (RBAC 4 levels)
+- Git Strategy 3-Mode System (Manual/Personal/Team)
+- TRUST 5 Quality Gates
+- Compliance (GDPR, CCPA, OWASP, SOC 2, ISO 27001)
+
+Use Cases:
+- Security constraint enforcement
+- Git workflow configuration
+- Compliance validation
+- Error handling protocols
+
+---
+
+## Usage Patterns
+
+### Loading Individual Modules
+
+```python
+# Load specific module
+from pathlib import Path
+
+skill_path = Path(".claude/skills/moai-foundation-core")
+module_path = skill_path / "modules" / "trust-5-framework.md"
+
+with open(module_path) as f:
+ content = f.read()
+```
+
+### Progressive Loading
+
+```python
+# Load progressively based on user needs
+class ModuleLoader:
+ def load_quick_reference(self, module_name: str):
+ """Load Quick Reference section only (~1K tokens)."""
+ content = self.load_module(module_name)
+ return self.extract_section(content, "Quick Reference")
+ 
+ def load_implementation(self, module_name: str):
+ """Load Implementation Guide (~3K tokens)."""
+ content = self.load_module(module_name)
+ return self.extract_section(content, "Implementation Guide")
+ 
+ def load_advanced(self, module_name: str):
+ """Load Advanced Patterns (~5K tokens)."""
+ content = self.load_module(module_name)
+ return self.extract_section(content, "Advanced Implementation")
+```
+
+### Searching Across Modules
+
+```python
+class ModuleSearch:
+ def search_topic(self, query: str) -> list:
+ """Search for topic across all modules."""
+ modules_dir = Path(".claude/skills/moai-foundation-core/modules")
+ results = []
+ 
+ for module_file in modules_dir.glob("*.md"):
+ with open(module_file) as f:
+ content = f.read()
+ 
+ if query.lower() in content.lower():
+ results.append({
+ "module": module_file.stem,
+ "matches": content.lower().count(query.lower())
+ })
+ 
+ return sorted(results, key=lambda x: x["matches"], reverse=True)
+
+# Usage
+searcher = ModuleSearch()
+results = searcher.search_topic("security")
+# Results: trust-5-framework (high), delegation-patterns (medium), etc.
+```
+
+---
+
+## Integration with SKILL.md
+
+The main SKILL.md file (409 lines, within 500-line limit) provides:
+- Quick overview of all 6 principles
+- Entry points to each module
+- Cross-references for deep dives
+- Works Well With integration
+
+Cross-Reference Pattern:
+```markdown
+<!-- In SKILL.md -->
+### 1. TRUST 5 Framework - Quality Assurance System
+
+Quick overview...
+
+Detailed Reference: [TRUST 5 Framework Module](modules/trust-5-framework.md)
+```
+
+---
+
+## Module Statistics
+
+| Module | Lines | Topics Covered | Use Cases |
+|--------|-------|----------------|-----------|
+| trust-5-framework | 982 | Quality gates, CI/CD, validation | 4 |
+| spec-first-tdd | 866 | SPEC, EARS, TDD, docs | 4 |
+| delegation-patterns | 757 | Sequential, parallel, conditional | 4 |
+| token-optimization | 656 | Budget, /clear, loading, models | 4 |
+| progressive-disclosure | 576 | 3 levels, 500-line limit, splitting | 4 |
+| modular-system | 588 | File structure, organization, discovery | 4 |
+| agents-reference | ~400 | 26 agents, 7 tiers, MCP Resume | 4 |
+| commands-reference | ~300 | 6 commands, workflow, /clear rules | 4 |
+| execution-rules | ~700 | Security, Git, compliance, RBAC | 4 |
+| Total | ~6,825 | 36 major topics | 36 use cases |
+
+---
+
+## Works Well With
+
+Skills:
+- moai-foundation-core (parent skill)
+- moai-cc-skill-factory (skill creation)
+- moai-core-agent-factory (agent creation)
+
+Agents:
+- skill-factory (module generation)
+- docs-manager (documentation)
+- quality-gate (validation)
+
+Commands:
+- /moai:1-plan (SPEC-First TDD)
+- /moai:2-run (TDD implementation)
+- /moai:3-sync (Documentation)
+- /clear (Token optimization)
+
+---
+
+Maintained by: MoAI-ADK Team
+Status: Production Ready
+Next Review: As needed when foundation principles evolve