moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

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

@@ -0,0 +1,265 @@
+# Practical Examples: MoAI-ADK Rules in Action
+
+## Example 1: Mandatory Skill Invocation
+
+### ❌ WRONG: Skipping Skill for TRUST Validation
+```
+User: "Check code quality of my new feature"
+Alfred: "Looking at your code...linting...checking coverage...
+Actually, looks good! No issues found."
+```
+
+**Problem**: Direct linting without `Skill("moai-foundation-trust")` → misses quality gates, context overhead
+
+### ✅ CORRECT: Using Skill Invocation
+```
+User: "Check code quality of my new feature"
+Alfred: Skill("moai-foundation-trust")
+Result: ✓ Structured TRUST 5 validation (Test, Readable, Unified, Secured, Trackable)
+```
+
+---
+
+## Example 2: AskUserQuestion for Ambiguous Requirements
+
+### ❌ WRONG: Making Assumptions
+```
+User: "Add user authentication to the app"
+Alfred: [Assumes OAuth] "I'll implement Google OAuth..."
+Reality: User wanted basic email/password auth
+Result: Wasted effort, wrong implementation
+```
+
+### ✅ CORRECT: Using AskUserQuestion
+```
+User: "Add user authentication to the app"
+Alfred: AskUserQuestion([
+  "What auth method?": [Email/Password, OAuth, JWT, Multi-factor],
+  "What scope?": [Admin users only, All users, Public signup],
+  "Session duration?": [24 hours, 7 days, Remember me]
+])
+User selects: [Email/Password, All users, 7 days]
+Alfred: "I'll implement email/password with 7-day sessions..."
+Result: ✓ Correct implementation, zero rework
+```
+
+---
+
+## Example 3: TAG Chain Validation Rules
+
+### ❌ WRONG: Orphan TAGs
+```python
+# src/auth/user.py
+def verify_email(token):  # @CODE:AUTH-015
+    """Verify user email with token"""
+    ...
+
+# PROBLEM: No corresponding @TEST:AUTH-015 in tests/
+# Result: TAG chain broken, no traceability
+```
+
+### ✅ CORRECT: Complete TAG Chain
+```python
+# tests/auth/test_email_verify.py
+def test_verify_email_with_valid_token():  # @TEST:AUTH-015
+    """Verify user email with token"""
+    ...
+    assert user.email_verified = True
+
+# src/auth/user.py
+def verify_email(token):  # @CODE:AUTH-015
+    """Verify user email with token"""
+    ...
+
+# README.md
+## Email Verification (AUTH-015)
+User can verify their email... # @DOC:AUTH-015
+
+# HISTORY
+- @TEST:AUTH-015: Added email verification test (2025-11-02)
+- @CODE:AUTH-015: Implemented token validation (2025-11-02)
+- @DOC:AUTH-015: Updated README (2025-11-02)
+
+# Result: ✓ Complete traceability from SPEC → TEST → CODE → DOC
+```
+
+---
+
+## Example 4: TRUST 5 Quality Gates
+
+### Scenario: Code Review with TRUST Validation
+
+**Before TRUST Check**:
+```python
+# user_service.py - 60% test coverage, no input validation
+def create_user(name, email, password):
+    user = User(name=name, email=email, password=password)
+    db.save(user)  # ❌ No validation, SQL injection risk
+    return user
+```
+
+**After Skill("moai-foundation-trust")**:
+```
+⚠️ TRUST 5 Validation Results:
+
+1. Test (85%+ required): ❌ FAIL
+   - Current: 60% coverage
+   - Issue: Missing edge case tests (empty email, duplicate email)
+
+2. Readable: ⚠️ WARNING
+   - Issue: No input validation docstring
+   - Fix: Add parameter validation comments
+
+3. Unified: ✅ PASS
+   - Pattern matches other services
+
+4. Secured: ❌ FAIL
+   - OWASP A04: SQL injection risk (no parameterized query)
+   - Fix: Use ORM or prepared statements
+
+5. Trackable: ❌ FAIL
+   - No @TAG assigned
+   - Fix: Add @TEST:USER-002 and @CODE:USER-002
+
+Action: Skill("moai-essentials-refactor") to fix security + add tests
+```
+
+---
+
+## Example 5: Skill Tier Usage Pattern
+
+### Scenario: Implementing "Add authentication dashboard"
+
+```
+User Request: "Add authentication dashboard"
+     ↓
+Step 1: Intent unclear → AskUserQuestion
+- Framework choice?
+- Admin vs user dashboard?
+- Real-time monitoring needed?
+     ↓
+Step 2: Create SPEC → Skill("moai-alfred-spec-authoring")
+     ↓
+Step 3: TDD Implementation → Skill("moai-foundation-trust")
+     ↓
+Step 4: Code Review → Skill("moai-essentials-review")
+     ↓
+Step 5: Git Workflow → Skill("moai-foundation-git")
+     ↓
+Step 6: Sync Documentation → Skill("moai-foundation-tags")
+     ↓
+Result: Complete implementation with TRUST 5 + TAG traceability
+```
+
+---
+
+## Example 6: EARS Requirement Syntax with Rules
+
+### ❌ WRONG: Vague Requirement
+```
+"User can view dashboard"
+```
+
+### ✅ CORRECT: EARS Syntax
+```
+@TAG:DASHBOARD-001
+
+Given a logged-in user with admin role
+When the user navigates to /admin/dashboard
+Then the system displays real-time metrics (CPU, memory, requests)
+And metrics update every 5 seconds
+And unauthorized users receive 403 Forbidden
+
+Optional:
+- User can export metrics as CSV
+- Metrics are cached for 60 seconds
+
+Unwanted Behaviors:
+- Dashboard does NOT expose raw logs
+- Dashboard does NOT allow system shutdown
+```
+
+**Why**: Skill("moai-foundation-ears") enforces clarity, reduces ambiguity
+
+---
+
+## Example 7: Command Sequence with Rules
+
+### Workflow: "I want to add email verification feature"
+
+```bash
+# Step 1: Initialize project (creates CLAUDE.md, config.json)
+/alfred:0-project
+
+# Step 2: Write SPEC
+/alfred:1-plan "Email Verification"
+→ Skill("moai-alfred-spec-metadata-extended") validates metadata
+→ Skill("moai-foundation-ears") validates requirement syntax
+→ Creates .moai/specs/SPEC-AUTH-015/
+
+# Step 3: TDD Implementation
+/alfred:2-run SPEC-AUTH-015
+→ Skill("moai-foundation-trust") enforces 85%+ test coverage
+→ RED → GREEN → REFACTOR cycle
+→ Creates @TEST, @CODE TAGs
+
+# Step 4: Sync Documentation
+/alfred:3-sync
+→ Skill("moai-foundation-git") enforces commit message format
+→ Skill("moai-foundation-tags") validates TAG chain
+→ Updates README, CHANGELOG with SPEC reference
+
+# Result: Complete feature with SPEC → TEST → CODE → DOC traceability
+```
+
+---
+
+## Example 8: When NOT to Use Skills (Exceptions)
+
+### ✅ LEGITIMATE: Direct tools without Skill()
+
+```
+# 1. Reading single file for context
+Read(file_path="/path/to/config.json")  ← Direct read OK
+
+# 2. Quick list of files
+Bash("ls src/")  ← Direct bash OK
+
+# 3. Git operations already wrapped in Skill
+Bash("git log")  ← Called from Skill("moai-foundation-git")  ← OK
+
+# 4. JIT context retrieval for current task
+Grep("authenticate" type:py)  ← OK for immediate task context
+```
+
+### ❌ WRONG: Skipping Skill When It Exists
+
+```
+# 1. TRUST validation
+❌ Direct: Bash("pytest --cov")
+✅ Correct: Skill("moai-foundation-trust")
+
+# 2. TAG validation
+❌ Direct: Bash("rg '@TAG:' -n")
+✅ Correct: Skill("moai-foundation-tags")
+
+# 3. SPEC authoring
+❌ Direct: Manual YAML writing
+✅ Correct: Skill("moai-foundation-specs")
+```
+
+---
+
+## Key Takeaways
+
+1. **Always use Skill() explicitly** for 55+ knowledge domains
+2. **Use AskUserQuestion** when user intent is ambiguous
+3. **Enforce TRUST 5** before every code completion
+4. **Maintain TAG chains** from SPEC → TEST → CODE → DOC
+5. **Use EARS syntax** for all requirements
+6. **Progressive disclosure** guides skill content layers
+7. **JIT retrieval** manages context efficiently
+
+---
+
+**Learn More**: See `reference.md` for complete rule definitions, decision trees, and validation procedures.