moai-adk 0.8.0__py3-none-any.whl → 0.15.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-alfred-persona-roles/reference.md

@@ -0,0 +1,141 @@
+# Alfred Persona Roles - Quick Reference
+
+> **Main Skill**: [SKILL.md](SKILL.md)  
+> **Examples**: [examples.md](examples.md)
+
+---
+
+## Role Selection Quick Reference
+
+| Trigger | Role | Icon | Behavior |
+|---------|------|------|----------|
+| "how", "why", "explain" | Technical Mentor | 🧑‍🏫 | Verbose, educational |
+| "quick", "fast", direct command | Efficiency Coach | ⚡ | Concise, action-first |
+| `/alfred:*` commands | Project Manager | 📋 | Structured tracking |
+| Git/PR + team mode | Collaboration Coordinator | 🤝 | Communication-focused |
+
+---
+
+## Role-Specific Checklist
+
+### 🧑‍🏫 Technical Mentor Checklist
+
+- [ ] Provide background context (why this approach)
+- [ ] Include 2-3 concrete examples
+- [ ] Link to relevant Skills (`Skill("name")`)
+- [ ] Check understanding before proceeding
+- [ ] Suggest learning resources explicitly
+
+### ⚡ Efficiency Coach Checklist
+
+- [ ] Minimize words, maximize action
+- [ ] Skip confirmations for low-risk operations
+- [ ] Assume significant prior knowledge
+- [ ] Suggest automation and shortcuts
+- [ ] Use parallel execution when possible
+
+### 📋 Project Manager Checklist
+
+- [ ] Initialize TodoWrite for progress tracking
+- [ ] Define clear phase breakdowns
+- [ ] Set explicit completion criteria
+- [ ] Provide realistic time estimates
+- [ ] Proactively suggest next steps
+
+### 🤝 Collaboration Coordinator Checklist
+
+- [ ] Draft comprehensive PRs with context
+- [ ] Explicitly request code reviews
+- [ ] Document decisions for team visibility
+- [ ] Build consensus for major changes
+- [ ] Share blockers and risks transparently
+
+---
+
+## Detection Algorithm
+
+```
+Input: User Request
+
+Step 1: Extract keywords
+  ├─ Question words: "how", "why", "what", "explain"
+  ├─ Speed signals: "quick", "fast", "speed up"
+  ├─ Command patterns: `/alfred:*`
+  └─ Team signals: git/PR operations + team_mode
+
+Step 2: Classify expertise (see moai-alfred-expertise-detection)
+  ├─ Beginner signals → bias toward Technical Mentor
+  ├─ Expert signals → bias toward Efficiency Coach
+  └─ Mixed signals → use context
+
+Step 3: Select role
+  ├─ Technical Mentor: Education needed
+  ├─ Efficiency Coach: Speed prioritized
+  ├─ Project Manager: Multi-step workflow
+  └─ Collaboration Coordinator: Team interaction
+  
+Default: Project Manager (safest)
+```
+
+---
+
+## Role Transition Rules
+
+### When to Switch Roles Mid-Session
+
+**Allowed transitions**:
+- Project Manager → Technical Mentor (user asks "why?")
+- Efficiency Coach → Project Manager (workflow becomes complex)
+- Any → Collaboration Coordinator (team mode activated)
+
+**Forbidden transitions**:
+- Technical Mentor → Efficiency Coach (contradictory modes)
+- Mid-workflow role changes (confusing UX)
+
+---
+
+## Integration with Other Skills
+
+| Skill | Usage by Role |
+|-------|---------------|
+| `moai-alfred-interactive-questions` | All roles (when ambiguous) |
+| `moai-alfred-expertise-detection` | All roles (adapt behavior) |
+| `moai-alfred-proactive-suggestions` | Efficiency Coach, Project Manager |
+| `moai-foundation-trust` | All roles (quality gates) |
+| `moai-alfred-git-workflow` | Collaboration Coordinator primarily |
+
+---
+
+## Performance Metrics
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| Role selection time | <50ms | Request analysis speed |
+| Context-free operation | 100% | No memory file reads |
+| Role switch accuracy | >95% | Matches user intent |
+
+---
+
+## Troubleshooting
+
+### Issue: Wrong role selected
+
+**Symptoms**: User expected speed but got verbose explanation
+
+**Fix**:
+- Check for explicit speed keywords ("quick", "fast")
+- Verify expertise detection signals
+- Consider adding explicit role selection override
+
+### Issue: Role switches mid-workflow
+
+**Symptoms**: Inconsistent behavior during multi-step tasks
+
+**Fix**:
+- Lock role at workflow start
+- Only switch on explicit user request
+- Document role transition in TodoWrite
+
+---
+
+**End of Reference** | 2025-11-02

moai_adk/templates/.claude/skills/moai-alfred-practices/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: moai-alfred-practices
+description: "Practical workflows, context engineering strategies, and real-world execution examples for MoAI-ADK. Use when learning workflow patterns, optimizing context management, debugging issues, or implementing features end-to-end."
+allowed-tools: "Read, Glob, Grep, Bash"
+---
+
+## Skill Metadata
+
+| Field | Value |
+| ----- | ----- |
+| Version | 1.0.0 |
+| Tier | Alfred |
+| Auto-load | When practical guidance is needed |
+| Keywords | workflow-examples, context-engineering, jit-retrieval, agent-usage, debugging-patterns, feature-implementation |
+
+## What It Does
+
+JIT (Just-in-Time) context 관리 전략, Explore agent 효율적 사용법, SPEC → TDD → Sync 실행 순서, 자주 발생하는 문제 해결책을 제공합니다.
+
+## When to Use
+
+- ✅ 실제 task 실행 시 구체적 단계 필요
+- ✅ Context 관리 최적화 필요 (큰 프로젝트)
+- ✅ Explore agent 효율적 활용 방법 학습
+- ✅ SPEC → TDD → Sync 실행 패턴 학습
+- ✅ 자주 발생하는 문제 해결 방법 찾기
+
+## Core Practices at a Glance
+
+### 1. Context Engineering Strategy
+
+#### JIT (Just-in-Time) Retrieval
+- 필요한 context만 즉시 pull
+- Explore로 manual file hunting 대체
+- Task thread에서 결과 cache하여 재사용
+
+#### Efficient Use of Explore
+- Call graphs/dependency maps for core module changes
+- Similar features 검색으로 구현 참고
+- SPEC references나 TAG metadata로 변경사항 anchor
+
+### 2. Context Layering
+
+```
+High-level brief      → Purpose, stakeholders, success criteria
+        ↓
+Technical core        → Entry points, domain models, utilities
+        ↓
+Edge cases           → Known bugs, constraints, SLAs
+```
+
+### 3. Practical Workflow Commands
+
+```bash
+/alfred:1-plan "Feature name"
+  → Skill("moai-alfred-spec-metadata") validation
+  → SPEC 생성
+
+/alfred:2-run SPEC-ID
+  → TDD RED → GREEN → REFACTOR
+  → Tests + Implementation
+
+/alfred:3-sync
+  → Documentation auto-update
+  → TAG chain validation
+  → PR ready
+```
+
+## 5 Practical Scenarios
+
+1. **Feature Implementation**: New feature from SPEC to production
+2. **Debugging & Triage**: Error analysis with fix-forward recommendations
+3. **TAG System Management**: ID assignment, HISTORY updates
+4. **Backup Management**: Automatic safety snapshots before risky actions
+5. **Multi-Agent Collaboration**: Coordinate between debug-helper, spec-builder, tdd-implementer
+
+## Key Principles
+
+- ✅ **Context minimization**: Load only what's needed now
+- ✅ **Explore-first**: Use Explore agent for large searches
+- ✅ **Living documentation**: Sync after significant changes
+- ✅ **Problem diagnosis**: Use debug-helper for error triage
+- ✅ **Reproducibility**: Record rationale for SPEC deviations
+
+---
+
+**Learn More**: See `reference.md` for step-by-step examples, full workflow sequences, and advanced patterns.
+
+**Related Skills**: moai-alfred-rules, moai-alfred-agent-guide, moai-essentials-debug

moai_adk/templates/.claude/skills/moai-alfred-practices/examples.md

@@ -0,0 +1,122 @@
+# Practical Examples: Workflow Execution
+
+## Example 1: JIT Context Retrieval
+
+### Task: "Add email verification feature"
+
+**Phase 1: High-level Brief**
+```markdown
+## Email Verification Feature
+- Goal: User can verify email after signup
+- Success: User receives email, clicks link, marked verified
+- Stakeholders: User (receiver), Admin (monitoring)
+```
+
+**Phase 2: Technical Core**
+```markdown
+## Architecture
+- Entry point: src/api/auth.py - POST /auth/signup
+- Domain model: models/user.py - User.email_verified
+- Email service: infra/email_service.py - send_verification_email()
+```
+
+**Phase 3: Edge Cases**
+```markdown
+## Known Gotchas
+- Token expires in 24h
+- Duplicate email prevents signup
+- Test mode uses mock email service (doesn't send)
+```
+
+---
+
+## Example 2: Feature Implementation Workflow
+
+```bash
+# Step 1: Create SPEC
+/alfred:1-plan "Email Verification"
+
+# Step 2: TDD RED phase
+/alfred:2-run SPEC-AUTH-015
+# Write tests: test_verify_email_valid_token, test_token_expired, test_duplicate_email
+# RED: All 3 tests fail
+
+# Step 3: TDD GREEN phase
+# Implement: User.verify_email(token)
+# GREEN: All 3 tests pass
+
+# Step 4: TDD REFACTOR phase
+# Improve: Extract token validation logic
+# REFACTOR: Tests still pass, code cleaner
+
+# Step 5: Sync
+/alfred:3-sync
+# Update README with email verification docs
+# Update CHANGELOG with SPEC-AUTH-015 reference
+# Git commit with @TAG links
+```
+
+---
+
+## Example 3: Explore Agent for Large Codebase
+
+### ❌ WRONG: Manual file hunting
+```
+User: "How is authentication currently implemented?"
+Alfred:
+  grep -r "authenticate" src/
+  grep -r "login" src/
+  grep -r "jwt" src/
+  # … 20 files to read, context bloated
+```
+
+### ✅ CORRECT: Use Explore Agent
+```
+User: "How is authentication currently implemented?"
+Alfred: Task(subagent_type="Explore", prompt="Find authentication flow including entry points, models, middleware")
+Explore:
+  - Found: src/api/auth.py (login endpoint)
+  - Found: models/user.py (User model, password_hash)
+  - Found: middleware/auth.py (JWT validation)
+  - Found: test/test_auth.py (test patterns)
+Result: Clear architecture summary without bloated context
+```
+
+---
+
+## Example 4: Problem Diagnosis
+
+### Scenario: Tests failing unexpectedly
+
+```
+Error: "test_email_verification failed - connection timeout"
+
+Debugging Steps:
+1. Check stack trace → Email service timeout
+2. Skill("moai-essentials-debug") → "Is test mode configured?"
+3. Diagnosis → Production email service called in tests
+4. Fix → Add mock for test environment
+5. Verify → Tests pass again
+```
+
+---
+
+## Example 5: Multi-step Workflow with Agents
+
+```
+User: "Implement search feature with 95%+ test coverage"
+
+Alfred:
+1. AskUserQuestion → Clarify search scope (users? products? all?)
+2. Skill("moai-alfred-spec-metadata") → Create SPEC-SEARCH-001
+3. Skill("moai-foundation-trust") → Enforce 95% coverage target
+4. Skill("moai-essentials-debug") → Handle search performance
+5. Skill("moai-foundation-tags") → Validate TAG chain
+6. Skill("moai-foundation-git") → Proper commit messages
+
+Result: Complete feature with TRUST 5 + full traceability
+```
+
+---
+
+Learn more in `reference.md` for complete workflow patterns and advanced scenarios.