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

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

@@ -0,0 +1,273 @@
+---
+name: moai-alfred-reporting
+version: 1.0.0
+created: 2025-11-02
+updated: 2025-11-02
+status: active
+description: Guide report writing and output formatting for Alfred operations
+keywords: ['reporting', 'output', 'formatting', 'documentation', 'communication']
+allowed-tools:
+  - Read
+---
+
+# Alfred Reporting Guide - Documentation & Communication
+
+## Skill Metadata
+
+| Field | Value |
+| ----- | ----- |
+| **Skill Name** | moai-alfred-reporting |
+| **Version** | 1.0.0 (2025-11-02) |
+| **Status** | Active |
+| **Tier** | Alfred |
+| **Purpose** | Guide report writing and output formatting best practices |
+
+---
+
+## What It Does
+
+Alfred uses consistent reporting patterns for task completion, documentation, and team communication.
+
+**Key capabilities**:
+- ✅ Screen output formatting (plain text, NO markdown syntax)
+- ✅ Internal document formatting (markdown, structured sections)
+- ✅ Sub-agent report templates
+- ✅ Command completion reporting
+- ✅ Language-aware output
+
+---
+
+## When to Use
+
+**Automatic triggers**:
+- Task completion → generate report summary
+- Command execution done (*/alfred:*) → report results
+- Documentation sync complete → report changes
+- Quality verification passed → report metrics
+
+**Manual reference**:
+- Understanding report structure
+- Formatting task completion summaries
+- Learning best practices for documentation
+
+---
+
+## Output Format Rules
+
+### Screen Output to User (Plain Text)
+
+**When responding directly to user in chat/prompt:**
+
+Use plain text format (NO markdown headers, tables, or special formatting):
+
+```
+Task Completion Summary:
+
+Status: ✅ Complete
+Duration: 2 hours
+Files Modified: 5
+Test Coverage: 95%
+
+Key Achievements:
+- Feature implemented
+- Tests passing
+- Documentation updated
+
+Next Steps:
+1. Review PR
+2. Merge to main
+3. Deploy
+```
+
+### Internal Documents (Markdown Format)
+
+**When creating files in `.moai/docs/`, `.moai/reports/`, `.moai/analysis/`:**
+
+Use markdown format with proper structure:
+
+```markdown
+## 🎊 Task Completion Report
+
+### Results
+- ✅ Item 1 completed
+- ✅ Item 2 completed
+
+### Metrics
+| Item | Result |
+|------|--------|
+| Coverage | 95% |
+| Validation | ✅ Passed |
+
+### Next Steps
+1. Action item
+2. Follow-up
+```
+
+---
+
+## Standard Report Template
+
+### Minimal Report (1-2 items)
+
+```markdown
+## ✅ [Task] Complete
+
+Status: Done
+Duration: X mins
+Next: [Recommended action]
+```
+
+### Standard Report (3-5 items)
+
+```markdown
+## 🎊 [Task] Complete
+
+### Results
+- ✅ Item 1
+- ✅ Item 2
+- ✅ Item 3
+
+### Metrics
+| Metric | Value |
+|--------|-------|
+| Coverage | 95% |
+| Speed | ✅ OK |
+
+### Next Steps
+1. Action 1
+2. Action 2
+```
+
+### Comprehensive Report (6+ items)
+
+```markdown
+## 📊 [Task] Detailed Report
+
+### Executive Summary
+One-sentence overview
+
+### Key Results
+- ✅ Accomplished
+- ✅ Accomplished
+- ✅ Accomplished
+
+### Quality Metrics
+| Category | Result | Status |
+|----------|--------|--------|
+| Test Coverage | 95% | ✅ Excellent |
+| Performance | Fast | ✅ Good |
+| Validation | Passed | ✅ Complete |
+
+### Files Modified
+- `src/feature.py` - Core implementation
+- `tests/test_feature.py` - Test suite
+- `README.md` - Documentation
+
+### @TAG Verification
+- ✅ SPEC → CODE connection
+- ✅ CODE → TEST connection
+- ✅ TEST → DOC connection
+
+### Blockers & Risks
+- None identified
+
+### Next Steps
+1. Create PR
+2. Request reviews
+3. Merge when approved
+```
+
+---
+
+## Sub-Agent Report Examples
+
+### spec-builder Completion Report
+
+```markdown
+## 📋 SPEC Creation Complete
+
+### Generated Artifacts
+- ✅ `.moai/specs/SPEC-001/spec.md`
+- ✅ `.moai/specs/SPEC-001/plan.md`
+- ✅ `.moai/specs/SPEC-001/acceptance.md`
+
+### Validation Results
+- ✅ EARS format compliance: 100%
+- ✅ @TAG chain created
+- ✅ Requirement coverage: Complete
+
+### Quality Gates
+- ✅ Clarity: High
+- ✅ Completeness: 100%
+- ✅ Traceability: Set up
+
+### Ready for Implementation
+Next: Run `/alfred:2-run SPEC-001`
+```
+
+### tdd-implementer Completion Report
+
+```markdown
+## 🚀 Implementation Complete
+
+### TDD Phases
+| Phase | Status | Duration |
+|-------|--------|----------|
+| RED | ✅ Tests failing | 5 mins |
+| GREEN | ✅ Implementation | 45 mins |
+| REFACTOR | ✅ Code improvement | 15 mins |
+
+### Implementation Files
+- ✅ `src/feature.py` (234 LOC)
+- ✅ `tests/test_feature.py` (156 LOC)
+
+### Quality Metrics
+- Test Coverage: 98%
+- Linting: 0 issues
+- Type Checking: 0 errors
+
+### @TAG Verification
+- ✅ SPEC → CODE links verified
+- ✅ CODE → TEST links verified
+
+### Ready for Sync
+Next: Run `/alfred:3-sync`
+```
+
+### doc-syncer Completion Report
+
+```markdown
+## 📚 Documentation Sync Complete
+
+### Updated Documents
+- ✅ `README.md` - Usage examples added
+- ✅ `.moai/docs/architecture.md` - Implementation details
+- ✅ `CHANGELOG.md` - v0.8.0 entries
+- ✅ `API.md` - Endpoint documentation
+
+### @TAG Verification
+- ✅ SPEC → CODE verified
+- ✅ CODE → TEST verified
+- ✅ TEST → DOC verified
+- ✅ All chains complete
+
+### Quality Checks
+- ✅ No orphan TAGs
+- ✅ All links valid
+- ✅ Formatting consistent
+
+### Ready to Merge
+Next: Create PR and merge to main
+```
+
+---
+
+## Key Principles
+
+1. **Format Consistency**: Always use structured templates
+2. **Language Awareness**: Match user's `conversation_language`
+3. **Progress Visibility**: Include metrics and status indicators
+4. **Actionable Output**: Always suggest next steps
+5. **Traceability**: Include @TAG verification when relevant
+
+---

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

@@ -0,0 +1,77 @@
+---
+name: moai-alfred-rules
+description: "Mandatory rules for Skill invocation, AskUserQuestion usage, TRUST principles, TAG validation, and TDD workflow. Use when validating workflow compliance, checking quality gates, enforcing MoAI-ADK standards, or verifying rule adherence."
+allowed-tools: "Read, Glob, Grep, Bash"
+---
+
+## Skill Metadata
+
+| Field | Value |
+| ----- | ----- |
+| Version | 1.0.0 |
+| Tier | Alfred |
+| Auto-load | When validating rules or quality gates |
+| Keywords | skill-invocation, ask-user-question, trust, tag, tdd, quality-gates, workflow-compliance |
+
+## What It Does
+
+MoAI-ADK의 10가지 필수 Skill 호출 규칙, 5가지 AskUserQuestion 시나리오, TRUST 5 품질 게이트, TAG 체인 규칙, TDD 워크플로우를 정의합니다.
+
+## When to Use
+
+- ✅ Skill() 호출이 mandatory인지 optional인지 판단 필요
+- ✅ 사용자 질문이 ambiguous할 때 AskUserQuestion 사용 여부 결정
+- ✅ 코드/커밋이 TRUST 5를 준수하는지 확인
+- ✅ TAG 체인 무결성 검증
+- ✅ 커밋 메시지 형식 확인
+- ✅ 품질 게이트(quality gate) 검증
+
+## Core Rules at a Glance
+
+### 10 Mandatory Skill Invocations
+
+| User Request | Skill | Pattern |
+|---|---|---|
+| TRUST validation, quality check | `moai-foundation-trust` | `Skill("moai-foundation-trust")` |
+| TAG validation, orphan detection | `moai-foundation-tags` | `Skill("moai-foundation-tags")` |
+| SPEC authoring, spec validation | `moai-foundation-specs` | `Skill("moai-foundation-specs")` |
+| EARS syntax, requirement formatting | `moai-foundation-ears` | `Skill("moai-foundation-ears")` |
+| Git workflow, branch management | `moai-foundation-git` | `Skill("moai-foundation-git")` |
+| Language detection, stack detection | `moai-foundation-langs` | `Skill("moai-foundation-langs")` |
+| Debugging, error analysis | `moai-essentials-debug` | `Skill("moai-essentials-debug")` |
+| Refactoring, code improvement | `moai-essentials-refactor` | `Skill("moai-essentials-refactor")` |
+| Performance optimization | `moai-essentials-perf` | `Skill("moai-essentials-perf")` |
+| Code review, quality review | `moai-essentials-review` | `Skill("moai-essentials-review")` |
+
+### 5 AskUserQuestion Scenarios
+
+Use `AskUserQuestion` when:
+1. Tech stack choice unclear (multiple frameworks/languages)
+2. Architecture decision needed (monolith vs microservices)
+3. User intent ambiguous (multiple valid interpretations)
+4. Existing component impacts unknown (breaking changes)
+5. Resource constraints unclear (budget, timeline)
+
+### TRUST 5 Quality Gates
+
+- **Test**: 85%+ coverage required
+- **Readable**: No code smells, SOLID principles
+- **Unified**: Consistent patterns, no duplicate logic
+- **Secured**: OWASP Top 10 checks, no secrets
+- **Trackable**: @TAG chain intact (SPEC→TEST→CODE→DOC)
+
+### TAG Chain Integrity Rules
+
+- Assign as `<DOMAIN>-<###>` (e.g., `AUTH-003`)
+- Create `@TEST` before `@CODE`
+- Document in HISTORY section
+- Never have orphan TAGs (TAG without corresponding code)
+
+## Progressive Disclosure
+
+Learn more in `reference.md` for complete rules, decision trees, and validation methods.
+
+---
+
+**Version**: 1.0.0
+**Related Skills**: moai-foundation-trust, moai-foundation-tags, moai-alfred-practices

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") 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.

moai_adk/templates/.claude/skills/moai-alfred-session-state/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: moai-alfred-session-state
+description: "Session state management, runtime state tracking, session handoff notes."
+tier: Alfred
+allowed-tools: "Read"
+---
+
+## What It Does
+
+세션 상태 관리, 진행 상황 추적, session handoff 규칙을 정의합니다.
+
+## When to Use
+
+- ✅ Session 상태 확인
+- ✅ Task handoff 준비
+
+---
+
+Learn more in `reference.md`.

moai_adk/templates/.claude/skills/moai-alfred-session-state/examples.md

@@ -0,0 +1,4 @@
+# Examples
+
+See `reference.md` for practical examples and usage patterns.
+