moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-foundation-core/modules/spec-ears-format.md

@@ -0,0 +1,200 @@
+# EARS Format Reference
+
+Purpose: Comprehensive guide to Easy Approach to Requirements Syntax (EARS) patterns for SPEC generation.
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+Parent: [spec-first-tdd.md](spec-first-tdd.md)
+
+---
+
+## EARS Pattern Overview
+
+EARS provides five requirement patterns for clear, unambiguous specifications:
+
+1. **Ubiquitous** - Always active requirements
+2. **Event-driven** - Triggered by specific events
+3. **State-driven** - Active during specific states
+4. **Unwanted** - Negative requirements (prevention)
+5. **Optional** - Nice-to-have features
+
+---
+
+## Pattern 1: Ubiquitous Requirements
+
+Syntax: `The system SHALL [action].`
+
+Example:
+```markdown
+### SPEC-001-REQ-01: User Registration (Ubiquitous)
+Pattern: Ubiquitous
+Statement: The system SHALL register users with email and password validation.
+
+Acceptance Criteria:
+- Email format validated (RFC 5322)
+- Password strength: ≥8 chars, mixed case, numbers, symbols
+- Duplicate email rejected with clear error
+- Success returns user ID and confirmation email sent
+
+Test Coverage Target: ≥90%
+```
+
+---
+
+## Pattern 2: Event-Driven Requirements
+
+Syntax: `WHEN [event], the system SHALL [action].`
+
+Example:
+```markdown
+### SPEC-001-REQ-02: JWT Token Generation (Event-driven)
+Pattern: Event-driven
+Statement: WHEN a user successfully authenticates, the system SHALL generate a JWT token with 1-hour expiry.
+
+Acceptance Criteria:
+- Token includes user ID, email, role claims
+- Token signed with RS256 algorithm
+- Expiry set to 1 hour from generation
+- Refresh token generated with 7-day expiry
+
+Test Coverage Target: ≥95%
+```
+
+---
+
+## Pattern 3: State-Driven Requirements
+
+Syntax: `WHILE [state], the system SHALL [action].`
+
+Example:
+```markdown
+### SPEC-001-REQ-03: Token Validation (State-driven)
+Pattern: State-driven
+Statement: WHILE a request includes Authorization header, the system SHALL validate JWT token before processing.
+
+Acceptance Criteria:
+- Expired tokens rejected with 401 Unauthorized
+- Invalid signature rejected with 401 Unauthorized
+- Valid token extracts user claims successfully
+- Token blacklist checked (revoked tokens)
+
+Test Coverage Target: ≥95%
+```
+
+---
+
+## Pattern 4: Unwanted Requirements
+
+Syntax: `The system SHALL NOT [action].`
+
+Example:
+```markdown
+### SPEC-001-REQ-04: Weak Password Prevention (Unwanted)
+Pattern: Unwanted
+Statement: The system SHALL NOT allow passwords from common password lists (top 10K).
+
+Acceptance Criteria:
+- Common passwords rejected (e.g., "password123")
+- Sequential patterns rejected (e.g., "abc123")
+- User-specific patterns rejected (e.g., email prefix)
+- Clear error message with improvement suggestions
+
+Test Coverage Target: ≥85%
+```
+
+---
+
+## Pattern 5: Optional Requirements
+
+Syntax: `WHERE [condition], the system SHOULD [action].`
+
+Example:
+```markdown
+### SPEC-001-REQ-05: OAuth2 Integration (Optional)
+Pattern: Optional
+Statement: WHERE user chooses, the system SHOULD support OAuth2 authentication via Google and GitHub.
+
+Acceptance Criteria:
+- OAuth2 providers configurable
+- User can link multiple providers to one account
+- Provider-specific profile data merged
+- Graceful fallback if provider unavailable
+
+Test Coverage Target: ≥80%
+```
+
+---
+
+## Complex Requirement Example
+
+Multi-pattern requirements for complex scenarios:
+
+```markdown
+### SPEC-002-REQ-03: Multi-Factor Authentication (Event-driven + State-driven)
+Pattern: Event-driven + State-driven
+Statement:
+- WHEN a user attempts login with MFA enabled (Event)
+- WHILE the MFA verification is pending (State)
+- The system SHALL send TOTP code and require verification within 5 minutes
+
+Acceptance Criteria:
+1. Event trigger: Login attempt detected
+2. State check: User has MFA enabled
+3. Action: Generate TOTP code (6 digits, 30s validity)
+4. Notification: Send code via SMS or email
+5. Verification: User submits code within 5 minutes
+6. Expiry: Code expires after 5 minutes
+7. Rate limiting: Max 3 failed attempts, then 15-minute lockout
+
+Test Scenarios:
+- Happy path: User submits valid code within time
+- Expired code: User submits code after 5 minutes
+- Invalid code: User submits incorrect code
+- Rate limit: User exceeds 3 failed attempts
+- Disabled MFA: User without MFA enabled
+```
+
+---
+
+## Complexity Analysis Template
+
+```yaml
+# .moai/specs/SPEC-001/complexity.yaml
+complexity_metrics:
+  total_requirements: 5
+  critical_requirements: 3
+
+  complexity_breakdown:
+    SPEC-001-REQ-01: Medium   # Standard CRUD + validation
+    SPEC-001-REQ-02: Medium   # JWT library integration
+    SPEC-001-REQ-03: High     # Security validation logic
+    SPEC-001-REQ-04: Low      # Lookup validation
+    SPEC-001-REQ-05: High     # External API integration
+
+  estimated_effort:
+    development: 8 hours
+    testing: 4 hours
+    total: 12 hours
+
+  risk_factors:
+    - Security-critical functionality
+    - External OAuth2 provider dependencies
+    - Token expiry edge cases
+
+  dependencies:
+    - PyJWT library
+    - bcrypt library
+    - OAuth2 client libraries
+```
+
+---
+
+## Works Well With
+
+- [spec-first-tdd.md](spec-first-tdd.md) - Main workflow overview
+- [spec-tdd-implementation.md](spec-tdd-implementation.md) - TDD patterns
+
+---
+
+Version: 1.0.0
+Last Updated: 2026-01-06

moai_adk/templates/.claude/skills/moai-foundation-core/modules/spec-first-tdd.md

@@ -0,0 +1,171 @@
+# SPEC-First TDD - Specification-Driven Development
+
+Purpose: Specification-driven test-driven development workflow ensuring clear requirements before implementation through EARS format and RED-GREEN-REFACTOR cycles.
+
+Version: 2.0.0 (Modular Split)
+Last Updated: 2026-01-06
+
+---
+
+## Quick Reference (30 seconds)
+
+SPEC-First TDD is MoAI-ADK's development methodology combining:
+
+1. SPEC Generation - EARS format requirements (/moai:1-plan)
+2. Test-Driven Development - RED-GREEN-REFACTOR (/moai:2-run)
+3. Documentation Sync - Auto-generated docs (/moai:3-sync)
+
+Three-Phase Workflow:
+```
+Phase 1: SPEC → spec-builder → .moai/specs/SPEC-XXX/spec.md
+Phase 2: TDD  → tdd-implementer → Code + Tests (≥85% coverage)
+Phase 3: Docs → docs-manager → API docs + diagrams
+```
+
+Token Budget: SPEC 30K | TDD 180K | Docs 40K | Total 250K
+
+Key Practice: Execute `/clear` after Phase 1 to save 45-50K tokens.
+
+EARS Patterns:
+- Ubiquitous: System SHALL always...
+- Event-driven: WHEN <event>, system SHALL...
+- State-driven: WHILE <state>, system SHALL...
+- Unwanted: System SHALL NOT...
+- Optional: WHERE possible, system SHOULD...
+
+Extended Documentation:
+- [EARS Format Reference](spec-ears-format.md) - Detailed EARS patterns and examples
+- [TDD Implementation](spec-tdd-implementation.md) - RED-GREEN-REFACTOR workflows
+
+---
+
+## Implementation Guide (5 minutes)
+
+### Phase 1: SPEC Generation
+
+Purpose: Define clear, testable requirements in EARS format before coding.
+
+Workflow:
+```bash
+# 1. Generate SPEC
+/moai:1-plan "Implement user authentication with JWT tokens"
+
+# 2. spec-builder creates:
+.moai/specs/SPEC-001/
+    spec.md           # EARS format requirements
+    acceptance.md     # Acceptance criteria
+    complexity.yaml   # Complexity analysis
+
+# 3. Execute /clear (mandatory)
+/clear    # Saves 45-50K tokens, prepares clean context
+```
+
+EARS Format Structure:
+
+```markdown
+---
+spec_id: SPEC-001
+title: User Authentication System
+version: 1.0.0
+complexity: Medium
+estimated_effort: 8-12 hours
+---
+
+## Requirements
+
+### SPEC-001-REQ-01: User Registration (Ubiquitous)
+Pattern: Ubiquitous
+Statement: The system SHALL register users with email and password validation.
+
+Acceptance Criteria:
+- Email format validated (RFC 5322)
+- Password strength: ≥8 chars, mixed case, numbers, symbols
+- Duplicate email rejected with clear error
+- Success returns user ID and confirmation email sent
+
+Test Coverage Target: ≥90%
+```
+
+---
+
+### Phase 2: Test-Driven Development
+
+RED-GREEN-REFACTOR Cycle:
+
+```python
+# RED: Write failing test first
+def test_register_user():
+    result = register_user("user@example.com", "SecureP@ssw0rd")
+    assert result.success is True  # Fails - function doesn't exist
+
+# GREEN: Minimal implementation
+def register_user(email, password):
+    return RegistrationResult(success=True, user=User())
+
+# REFACTOR: Improve quality
+def register_user(email: str, password: str) -> RegistrationResult:
+    """Register new user with email and password.
+
+    Implements SPEC-001-REQ-01
+    """
+    # Validation, hashing, database operations
+    return RegistrationResult(success=True, user=user)
+```
+
+Coverage Validation:
+```bash
+# Run tests with coverage
+pytest tests/auth/test_registration.py --cov=src/auth/registration --cov-report=html
+```
+
+---
+
+### Phase 3: Documentation Synchronization
+
+Workflow:
+```bash
+# 1. Generate documentation
+/moai:3-sync SPEC-001
+
+# 2. docs-manager creates:
+.moai/specs/SPEC-001/
+    docs/
+        api.md           # API reference
+        architecture.md  # Architecture diagram
+        testing.md       # Test report
+        report.md        # Implementation summary
+```
+
+---
+
+## Advanced Patterns
+
+For comprehensive implementation patterns including MFA examples, iterative SPEC refinement, and CI/CD integration, see:
+
+- [EARS Format Reference](spec-ears-format.md) - All EARS patterns with examples
+- [TDD Implementation](spec-tdd-implementation.md) - Advanced TDD workflows
+
+---
+
+## Works Well With
+
+Agents:
+- spec-builder - EARS format SPEC generation
+- tdd-implementer - RED-GREEN-REFACTOR execution
+- quality-gate - TRUST 5 validation
+- docs-manager - Documentation generation
+
+Skills:
+- moai-workflow-testing - Test frameworks
+
+Commands:
+- /moai:1-plan - SPEC generation (Phase 1)
+- /moai:2-run - TDD implementation (Phase 2)
+- /moai:3-sync - Documentation sync (Phase 3)
+- /clear - Token optimization between phases
+
+---
+
+Version: 2.0.0
+Last Updated: 2026-01-06
+Status: Production Ready

moai_adk/templates/.claude/skills/moai-foundation-core/modules/spec-tdd-implementation.md

@@ -0,0 +1,275 @@
+# TDD Implementation Patterns
+
+Purpose: Advanced RED-GREEN-REFACTOR workflows and test implementation patterns for SPEC-First TDD.
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+Parent: [spec-first-tdd.md](spec-first-tdd.md)
+
+---
+
+## Complete TDD Example
+
+### User Registration Implementation
+
+```python
+# tests/auth/test_registration.py
+import pytest
+from src.auth.registration import register_user
+from src.exceptions import ValidationError
+
+class TestUserRegistration:
+    """Test suite for SPEC-001-REQ-01: User Registration."""
+
+    def test_register_user_success(self):
+        """Test successful registration with valid data."""
+        result = register_user("user@example.com", "SecureP@ssw0rd")
+        assert result.success is True
+        assert result.user.email == "user@example.com"
+        assert result.confirmation_sent is True
+
+    def test_register_user_invalid_email(self):
+        """Test registration fails with invalid email format."""
+        with pytest.raises(ValidationError, match="Invalid email format"):
+            register_user("invalid-email", "SecureP@ssw0rd")
+
+    def test_register_user_duplicate_email(self):
+        """Test registration fails with duplicate email."""
+        register_user("user@example.com", "SecureP@ssw0rd")
+        with pytest.raises(ValidationError, match="Email already registered"):
+            register_user("user@example.com", "AnotherP@ssw0rd")
+
+    def test_register_user_weak_password(self):
+        """Test registration fails with weak password."""
+        weak_passwords = [
+            "short",            # Too short
+            "alllowercase1",    # No uppercase
+            "ALLUPPERCASE1",    # No lowercase
+            "NoNumbersHere!",   # No digits
+            "NoSymbols123"      # No symbols
+        ]
+
+        for weak_pwd in weak_passwords:
+            with pytest.raises(ValidationError, match="Password must be"):
+                register_user("user@example.com", weak_pwd)
+
+    def test_register_user_password_hashing(self):
+        """Test password is properly hashed (not stored plain text)."""
+        result = register_user("user@example.com", "SecureP@ssw0rd")
+        assert result.user.password_hash != "SecureP@ssw0rd"
+        assert result.user.password_hash.startswith("$2b$")
+```
+
+---
+
+## Refactored Implementation
+
+```python
+# src/auth/registration.py
+from dataclasses import dataclass
+from typing import Optional
+import bcrypt
+import re
+
+EMAIL_REGEX = re.compile(r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$')
+PASSWORD_MIN_LENGTH = 8
+
+@dataclass
+class RegistrationResult:
+    """Result of user registration attempt."""
+    success: bool
+    user: Optional[User]
+    confirmation_sent: bool
+    error: Optional[str] = None
+
+def register_user(email: str, password: str) -> RegistrationResult:
+    """Register new user with email and password.
+
+    Implements SPEC-001-REQ-01: User Registration (Ubiquitous)
+
+    Args:
+        email: User email address (must be valid format)
+        password: User password (≥8 chars, mixed case, numbers, symbols)
+
+    Returns:
+        RegistrationResult with user data or error
+
+    Raises:
+        ValidationError: If email or password invalid
+    """
+    if not EMAIL_REGEX.match(email):
+        raise ValidationError("Invalid email format")
+
+    existing_user = User.query.filter_by(email=email).first()
+    if existing_user:
+        raise ValidationError("Email already registered")
+
+    if not _is_password_strong(password):
+        raise ValidationError(
+            "Password must be ≥8 characters with mixed case, numbers, and symbols"
+        )
+
+    password_hash = bcrypt.hashpw(
+        password.encode('utf-8'),
+        bcrypt.gensalt(rounds=12)
+    ).decode('utf-8')
+
+    user = User(email=email, password_hash=password_hash)
+    db_session.add(user)
+    db_session.commit()
+
+    confirmation_sent = send_confirmation_email(user.email, user.id)
+
+    return RegistrationResult(
+        success=True,
+        user=user,
+        confirmation_sent=confirmation_sent
+    )
+
+def _is_password_strong(password: str) -> bool:
+    """Validate password strength."""
+    if len(password) < PASSWORD_MIN_LENGTH:
+        return False
+
+    has_upper = any(c.isupper() for c in password)
+    has_lower = any(c.islower() for c in password)
+    has_digit = any(c.isdigit() for c in password)
+    has_symbol = any(not c.isalnum() for c in password)
+
+    return all([has_upper, has_lower, has_digit, has_symbol])
+```
+
+---
+
+## MFA Implementation Example
+
+```python
+# RED PHASE: Complex test scenario
+def test_mfa_verification_with_valid_code():
+    """SPEC-002-REQ-03: MFA verification happy path."""
+    user = create_user_with_mfa_enabled()
+    login_attempt = initiate_login(user.email, user.password)
+    totp_code = get_pending_totp_code(user.id)
+
+    result = verify_mfa(user.id, code=totp_code, timestamp=datetime.now())
+
+    assert result.success is True
+    assert result.token is not None
+    assert result.mfa_verified is True
+
+def test_mfa_verification_with_expired_code():
+    """SPEC-002-REQ-03: MFA code expiry."""
+    user = create_user_with_mfa_enabled()
+    totp_code = get_pending_totp_code(user.id)
+
+    result = verify_mfa(
+        user.id, code=totp_code,
+        timestamp=datetime.now() + timedelta(minutes=6)
+    )
+
+    assert result.success is False
+    assert result.error == "Code expired"
+
+def test_mfa_rate_limiting():
+    """SPEC-002-REQ-03: Rate limiting after failed attempts."""
+    user = create_user_with_mfa_enabled()
+
+    for _ in range(3):
+        verify_mfa(user.id, code="000000")
+
+    result = verify_mfa(user.id, code="123456")
+
+    assert result.success is False
+    assert "Too many failed attempts" in result.error
+```
+
+---
+
+## Iterative SPEC Refinement
+
+```python
+# Initial SPEC (v1.0.0)
+# SPEC-003-REQ-01: File upload with size limit (10MB)
+
+# Implementation reveals edge case
+# → User uploads 9.9MB file successfully
+# → But total storage exceeds user quota
+
+# Refined SPEC (v1.1.0)
+# SPEC-003-REQ-01: File upload with size and quota validation
+# - Single file limit: 10MB
+# - User quota limit: 100MB total
+# - Validation: Check both limits before accepting upload
+
+# Updated test
+def test_file_upload_exceeds_quota():
+    """SPEC-003-REQ-01 v1.1.0: Quota validation."""
+    user = create_user(quota_limit_mb=100)
+    upload_files(user, total_size_mb=95)
+
+    result = upload_file(user, file_size_mb=8)
+
+    assert result.success is False
+    assert result.error == "Upload would exceed storage quota"
+```
+
+---
+
+## CI/CD Pipeline Integration
+
+```yaml
+# .github/workflows/spec-tdd-pipeline.yml
+name: SPEC-First TDD Pipeline
+
+on:
+  push:
+    paths:
+      - '.moai/specs/**'
+      - 'src/**'
+      - 'tests/**'
+
+jobs:
+  spec-validation:
+    name: "Phase 1: SPEC Validation"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate SPEC format
+        run: python .moai/scripts/validate_spec.py
+      - name: Check requirement traceability
+        run: python .moai/scripts/check_traceability.py
+
+  tdd-implementation:
+    name: "Phase 2: TDD Implementation"
+    needs: spec-validation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run RED phase tests
+        run: pytest tests/ -v --tb=short || true
+      - name: Verify tests exist for all requirements
+        run: python .moai/scripts/verify_test_coverage_mapping.py
+
+  quality-gates:
+    name: "Phase 3: Quality Gates"
+    needs: tdd-implementation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run tests with coverage
+        run: pytest --cov=src --cov-fail-under=85
+      - name: Validate TRUST 5
+        run: python .moai/scripts/validate_trust5.py
+```
+
+---
+
+## Works Well With
+
+- [spec-first-tdd.md](spec-first-tdd.md) - Main workflow overview
+- [spec-ears-format.md](spec-ears-format.md) - EARS patterns
+
+---
+
+Version: 1.0.0
+Last Updated: 2026-01-06