moai-adk 0.10.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

moai_adk/templates/.moai/memory/SKILLS-DESCRIPTION-POLICY.md

@@ -1,218 +0,0 @@
-# Skills Description 개선 정책
-
-> MoAI-ADK의 모든 Skills에 적용되는 description 작성 표준
-
----
-
-## 🎯 설명 (Description) 작성 원칙
-
-### 1. 기본 구조
-
-모든 Skill의 description은 다음 3가지를 포함해야 합니다:
-
-```
-[What it does]: 간단한 기능 설명 (8-12 단어)
-[Key capabilities]: 핵심 기능 목록 (2-3개)
-[When to use]: 사용 시점 (3-5개 트리거 키워드, "Use when" 사용)
-```
-
-### 2. 작성 템플릿
-
-**기본 템플릿**:
-```
-description: [기능 설명]. [핵심 기능]. Use when [트리거1], [트리거2], or [트리거3].
-```
-
-**확장 템플릿** (필요 시):
-```
-description: [기능 설명]. [핵심 기능1], [핵심 기능2]. Use when [트리거1], [트리거2], [트리거3], or [트리거4]. Automatically activates [연관 Skills] for [목적].
-```
-
-### 3. Skills 카테고리별 템플릿
-
-#### Foundation Skills (moai-foundation-*)
-```
-description: [기능]. [핵심 기능 (예: validation, authoring)]. Use when [작업1], [작업2], [작업3], or [작업4].
-```
-**예시**:
-- ✅ "Validates SPEC YAML frontmatter (7 required fields) and HISTORY section. Use when creating SPEC documents, validating SPEC metadata, checking SPEC structure, or authoring specifications."
-- ❌ "SPEC metadata validation" (너무 짧음)
-
-#### Alfred Skills (moai-alfred-*)
-```
-description: [기능]. [핵심 능력]. Use when [검증/분석/관리 대상], [조건], or [상황]. Automatically activates [연관 Skills] for [목적].
-```
-**예시**:
-- ✅ "Validates TRUST 5-principles (Test 85%+, Code constraints, Architecture unity, Security, TAG trackability). Use when validating code quality, checking TRUST compliance, verifying test coverage, or analyzing security patterns. Automatically activates moai-foundation-trust and language-specific skills for comprehensive validation."
-- ❌ "TRUST validation" (너무 짧고 트리거 키워드 없음)
-
-#### Language Skills (moai-lang-*)
-```
-description: [언어] best practices with [주요 도구]. Use when [개발 활동], [패턴], or [특수 케이스].
-```
-**예시**:
-- ✅ "Python best practices with pytest, mypy, ruff, black. Use when writing Python code, implementing tests, type-checking, formatting code, or following PEP standards."
-- ❌ "Python best practices" (너무 일반적)
-
-#### Domain Skills (moai-domain-*)
-```
-description: [도메인] development with [주요 기술/패턴]. Use when [도메인 활동1], [도메인 활동2], or [특수 상황].
-```
-**예시**:
-- ✅ "Backend API development with REST patterns, authentication, error handling. Use when designing REST APIs, implementing authentication, or building backend services."
-- ❌ "Backend development" (구체성 부족)
-
-### 4. 트리거 키워드 가이드
-
-#### 작업 중심 키워드
-- "creating [artifact]", "writing [code/docs]", "implementing [feature]"
-- "validating [aspect]", "checking [quality]", "verifying [compliance]"
-- "analyzing [code/data]", "debugging [issue]", "diagnosing [problem]"
-
-#### 조건 중심 키워드
-- "when working with [file type/framework]"
-- "when developing [feature/component]"
-- "when applying [pattern/practice]"
-
-#### 상황 중심 키워드
-- "for [workflow/process]", "during [phase/stage]"
-- "to [achieve goal/outcome]"
-
-### 5. 금지 사항 (Anti-patterns)
-
-❌ **너무 짧음**:
-```
-description: Helps with documents
-```
-
-❌ **트리거 키워드 없음**:
-```
-description: PDF processing tool
-```
-
-❌ **"I can", "You can" 사용** (첫 인칭 회피):
-```
-description: I help you process Excel files
-```
-
-❌ **기술적 세부사항만**:
-```
-description: Uses pdfplumber library
-```
-
----
-
-## 📊 Skills 목록별 개선 체크리스트
-
-### Priority 1: Foundation Skills (7개)
-- [ ] moai-foundation-specs ✅ 완료
-- [ ] moai-foundation-ears ✅ 완료
-- [ ] moai-foundation-tags
-- [ ] moai-foundation-trust
-- [ ] moai-foundation-langs
-- [ ] moai-claude-code
-- [ ] moai-foundation-git
-
-### Priority 2: Alfred Skills (10개)
-- [ ] moai-alfred-tag-scanning
-- [ ] moai-alfred-trust-validation
-- [ ] moai-alfred-spec-metadata-validation
-- [ ] moai-alfred-code-reviewer
-- [ ] moai-alfred-git-workflow
-- [ ] moai-alfred-ears-authoring
-- [ ] moai-alfred-debugger-pro
-- [ ] moai-alfred-language-detection
-- [ ] moai-alfred-performance-optimizer
-- [ ] moai-alfred-refactoring-coach
-
-### Priority 3: Language Skills (20개)
-- moai-lang-typescript
-- moai-lang-python
-- moai-lang-go
-- moai-lang-rust
-- moai-lang-java
-- ... (14개 더)
-
-### Priority 4: Domain Skills (12개)
-- moai-domain-backend
-- moai-domain-frontend
-- moai-domain-web-api
-- moai-domain-database
-- ... (8개 더)
-
-### Priority 5: Essentials Skills (4개)
-- moai-essentials-debug
-- moai-essentials-review
-- moai-essentials-refactor
-- moai-essentials-perf
-
----
-
-## 🔧 개선 방법
-
-### 방법 1: 개별 Edit (고품질)
-각 Skill의 `description` 필드를 수작업 Edit
-- 이점: 각 Skill에 최적화된 description
-- 단점: 시간이 오래 걸림 (60+ Skills)
-
-### 방법 2: 정책 기반 일괄 개선 (효율성)
-템플릿을 기반으로 Pattern matching으로 우선순위별 개선
-1. Priority 1-2: 개별 Edit (가장 중요)
-2. Priority 3-5: 템플릿 기반 일괄 적용
-
-### 현재 진행 상태
-- ✅ moai-foundation-specs (Priority 1)
-- ✅ moai-foundation-ears (Priority 1)
-- ⏳ 나머지 50+ Skills (Priority 2-5)
-
----
-
-## 📝 작성 예시
-
-### 좋은 예시
-
-#### Foundation Skill
-```yaml
-description: Validates SPEC YAML frontmatter (7 required fields id, version, status, created, updated, author, priority) and HISTORY section. Use when creating SPEC documents, validating SPEC metadata, checking SPEC structure, or authoring specifications.
-```
-
-#### Alfred Skill
-```yaml
-description: Generates descriptive commit messages by analyzing git diffs. Use when writing commit messages, reviewing staged changes, or summarizing code modifications. Automatically activates git-workflow skill for advanced patterns.
-```
-
-#### Language Skill
-```yaml
-description: TypeScript best practices with Vitest, Biome, strict typing. Use when implementing TypeScript code, writing tests, checking code quality, or applying type safety patterns.
-```
-
-#### Domain Skill
-```yaml
-description: REST API design patterns with authentication, versioning, error handling. Use when designing REST APIs, implementing authentication, building backend services, or managing API versions.
-```
-
-### 수정 전 vs 수정 후
-
-| Skill | Before | After |
-|-------|--------|-------|
-| moai-foundation-specs | "Validates SPEC YAML frontmatter (7 required fields) and HISTORY section" | "Validates SPEC YAML frontmatter (7 required fields id, version, status, created, updated, author, priority) and HISTORY section. Use when creating SPEC documents, validating SPEC metadata, checking SPEC structure, or authoring specifications." |
-| moai-foundation-ears | "EARS requirement authoring guide (Ubiquitous/Event/State/Optional/Constraints)" | "EARS requirement authoring guide covering Ubiquitous/Event/State/Optional/Constraints syntax patterns. Use when writing requirements, authoring specifications, defining system behavior, or creating functional requirements." |
-
----
-
-## ✅ 최종 검증 체크리스트
-
-각 Skill의 description이 다음을 만족하는지 확인:
-
-- [ ] **"What it does"**: 명확한 기능 설명 (명사 + 동사)
-- [ ] **"Use when"**: 3~5개 구체적 트리거 키워드 포함
-- [ ] **길이**: 한 줄 (150-200 자 권장)
-- [ ] **관계**: 연관된 Skills 명시 (선택)
-- [ ] **발견성**: 검색 키워드 포함 (sub-agent가 발견 가능)
-- [ ] **첫 인칭 회피**: "I", "You", "Our" 사용 안 함
-- [ ] **기술 중심성 회피**: 라이브러리/도구명보다 기능/목적 우선
-
----
-
-**작성일**: 2025-10-20
-**최종 업데이트**: Phase 2 진행 중

moai_adk/templates/.moai/memory/gitflow-protection-policy.md

@@ -1,330 +0,0 @@
-# GitFlow Protection Policy
-
-**Document ID**: @DOC:GITFLOW-POLICY-ALIAS
-**Published**: 2025-10-17
-**Updated**: 2025-10-29
-**Status**: **Enforced via GitHub Branch Protection** (v0.8.3+)
-**Scope**: Personal and Team modes
-
----
-
-## Overview
-
-MoAI-ADK **enforces** a GitFlow-inspired workflow through GitHub Branch Protection. As of v0.8.3, the `main` branch is protected and requires Pull Requests for all changes, including from administrators.
-
-**What Changed**: Previously (v0.3.5-v0.8.2), we used an advisory approach with warnings. Now we enforce proper GitFlow to ensure code quality and prevent accidental direct pushes to main.
-
-## Key Requirements (Enforced)
-
-### 1. Main Branch Access (Enforced)
-
-| Requirement | Summary | Enforcement |
-|-------------|---------|-------------|
-| **Merge via develop** | MUST merge `develop` into `main` | ✅ Enforced |
-| **Feature branches off develop** | MUST branch from `develop` and raise PRs back to `develop` | ✅ Enforced |
-| **Release process** | Release flow: `develop` → `main` (PR required) | ✅ Enforced |
-| **Force push** | Blocked on `main` | ✅ Blocked |
-| **Direct push** | Blocked on `main` (PR required) | ✅ Blocked |
-
-### 2. Git Workflow (Required)
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                ENFORCED GITFLOW                         │
-│         (GitHub Branch Protection Active)               │
-└─────────────────────────────────────────────────────────┘
-
-        develop (required base branch)
-          ↑     ↓
-    ┌─────────────────┐
-    │                 │
-    │   developer work │
-    │                 │
-    ↓                 ↑
-feature/SPEC-{ID}   [PR: feature -> develop]
-                     [code review + approval]
-                     [Merge to develop]
-
-    develop (stable)
-         ↓
-         │   (release manager prepares)
-         ↓
-    [PR: develop -> main]
-    [Code review + approval REQUIRED]
-    [All discussions resolved]
-    [CI/CD validation]
-    [tag creation]
-         ↓
-       main (protected release)
-```
-
-**Enforcement**: Direct pushes to `main` are **blocked** via GitHub Branch Protection. All changes must go through Pull Requests.
-
-## Technical Implementation
-
-### Pre-push Hook (Advisory Mode)
-
-**Location**: `.git/hooks/pre-push`  
-**Purpose**: Warn on `main` branch pushes without blocking them
-
-```bash
-# When attempting to push to main:
-⚠️  ADVISORY: Non-standard GitFlow detected
-
-Current branch: feature/SPEC-123
-Target branch: main
-
-Recommended GitFlow workflow:
-  1. Work on feature/SPEC-{ID} branch (created from develop)
-  2. Push to feature/SPEC-{ID} and create PR to develop
-  3. Merge into develop after code review
-  4. When develop is stable, create PR from develop to main
-  5. Release manager merges develop -> main with tag
-
-✓ Push will proceed (flexibility mode enabled)
-```
-
-### Force Push Advisory
-
-```bash
-⚠️  ADVISORY: Force-push to main branch detected
-
-Recommended approach:
-  - Use GitHub PR with proper code review
-  - Ensure changes are merged via fast-forward
-
-✓ Push will proceed (flexibility mode enabled)
-```
-
----
-
-## Workflow Examples
-
-### Scenario 1: Standard Feature Development (Recommended)
-
-```bash
-# 1. Sync latest code from develop
-git checkout develop
-git pull origin develop
-
-# 2. Create a feature branch (from develop)
-git checkout -b feature/SPEC-001-new-feature
-
-# 3. Implement the change
-# ... write code and tests ...
-
-# 4. Commit
-git add .
-git commit -m "..."
-
-# 5. Push
-git push origin feature/SPEC-001-new-feature
-
-# 6. Open a PR: feature/SPEC-001-new-feature -> develop
-
-# 7. Merge into develop after review and approval
-```
-
-### Scenario 2: Fast Hotfix (Flexible)
-
-```bash
-# When an urgent fix is required:
-
-# Option 1: Recommended (via develop)
-git checkout develop
-git checkout -b hotfix/critical-bug
-# ... apply fix ...
-git push origin hotfix/critical-bug
-# Open PRs: hotfix -> develop -> main
-
-# Option 2: Direct fix on main (allowed, not recommended)
-git checkout main
-# ... apply fix ...
-git commit -m "Fix critical bug"
-git push origin main  # ⚠️ Advisory warning appears but push continues
-```
-
-### Scenario 3: Release (Standard or Flexible)
-
-```bash
-# Standard approach (recommended):
-git checkout develop
-gh pr create --base main --head develop --title "Release v1.0.0"
-
-# Direct push (allowed):
-git checkout develop
-git push origin main  # ⚠️ Advisory warning appears but push continues
-git tag -a v1.0.0 -m "Release v1.0.0"
-git push origin v1.0.0
-```
-
----
-
-## Policy Modes
-
-### Strict Mode (Active, v0.8.3+) ✅ ENFORCED
-
-**GitHub Branch Protection Enabled**:
-- ✅ **enforce_admins: true** - Administrators must follow all rules
-- ✅ **required_pull_request_reviews** - 1 approval required
-- ✅ **required_conversation_resolution** - All discussions must be resolved
-- ✅ **Block direct pushes to `main`** - PR required for all users
-- ✅ **Block force pushes** - Prevents history rewriting
-- ✅ **Block branch deletion** - Protects main from accidental deletion
-
-**What This Means**:
-- ❌ No one (including admins) can push directly to `main`
-- ✅ All changes must go through Pull Requests
-- ✅ PRs require code review approval
-- ✅ All code discussions must be resolved before merge
-- ✅ Enforces proper GitFlow: feature → develop → main
-
-### Advisory Mode (Legacy, v0.3.5 - v0.8.2)
-
-- ⚠️ Warned but allowed direct pushes to `main`
-- ⚠️ Warned but allowed force pushes
-- ⚠️ Recommended best practices while preserving flexibility
-- ❌ **Deprecated** - Replaced by Strict Mode for better quality control
-
----
-
-## Recommended Checklist
-
-Every contributor should ensure:
-
-- [ ] `.git/hooks/pre-push` exists and is executable (755)
-- [ ] Feature branches fork from `develop`
-- [ ] Pull requests target `develop`
-- [ ] Releases merge `develop` → `main`
-
-**Verification Commands**:
-```bash
-ls -la .git/hooks/pre-push
-git branch -vv
-```
-
----
-
-## FAQ
-
-**Q: Can we merge into `main` from branches other than `develop`?**  
-A: Yes. You will see an advisory warning, but the merge proceeds. The recommended path remains `develop` → `main`.
-
-**Q: Are force pushes allowed?**  
-A: Yes. You receive a warning, but the push succeeds. Use with caution.
-
-**Q: Can we commit/push directly to `main`?**  
-A: Yes. Expect an advisory warning, yet the push continues.
-
-**Q: Can I disable the hook entirely?**  
-A: Yes. Remove `.git/hooks/pre-push` or strip its execute permission.
-
-**Q: Why switch to Advisory Mode?**
-A: Advisory Mode was used in v0.3.5-v0.8.2. As of v0.8.3, we've switched to Strict Mode with GitHub Branch Protection for better quality control.
-
-**Q: What if develop falls behind main?**
-A: This can happen when hotfixes or releases go directly to main. Regularly sync main → develop to prevent divergence. See "Maintaining develop-main Sync" section below.
-
-**Q: Can I bypass branch protection in emergencies?**
-A: No. Even administrators must follow the PR process. For true emergencies, temporarily disable protection via GitHub Settings (requires admin access), but re-enable immediately after.
-
----
-
-## Maintaining develop-main Sync
-
-### ⚠️ Critical Rule: develop Must Stay Current
-
-**Problem**: When main receives direct commits (hotfixes, emergency releases) without syncing back to develop, GitFlow breaks:
-
-```
-❌ BAD STATE:
-develop: 3 commits ahead, 29 commits behind main
-- develop has outdated dependencies
-- New features branch from old code
-- Merge conflicts multiply over time
-```
-
-### Signs of Drift
-
-Monitor for these warnings:
-- `git status` shows "Your branch is X commits behind main"
-- Feature branches conflict with main during PR
-- CI/CD failures due to dependency mismatches
-- Version numbers in develop don't match main
-
-### Recovery Procedure
-
-When develop falls behind main:
-
-1. **Assess the Gap**
-   ```bash
-   git log --oneline develop..main  # Commits in main but not develop
-   git log --oneline main..develop  # Commits in develop but not main
-   ```
-
-2. **Sync Strategy: Merge main into develop (Recommended)**
-   ```bash
-   git checkout develop
-   git pull origin develop        # Get latest develop
-   git merge main                 # Merge main into develop
-   # Resolve conflicts if any (prefer main for version/config files)
-   git push origin develop
-   ```
-
-3. **Emergency Only: Reset develop to main (Destructive)**
-   ```bash
-   # ⚠️ ONLY if develop's unique commits are unwanted
-   git checkout develop
-   git reset --hard main
-   git push origin develop --force
-   ```
-
-### Prevention: Regular Sync Schedule
-
-**After every main release** (REQUIRED):
-```bash
-# Immediately after merging develop → main:
-git checkout develop
-git merge main
-git push origin develop
-```
-
-**Weekly maintenance** (for active projects):
-```bash
-# Every Monday morning:
-git checkout develop
-git pull origin main
-git push origin develop
-```
-
-### Real-World Case Study (2025-10-29)
-
-**Situation**: develop was 29 commits behind main due to:
-- v0.8.2, v0.8.3 released directly to main
-- No reverse sync to develop
-- Feature branches contained outdated code
-
-**Resolution**:
-- Merged main → develop (14 file conflicts)
-- Resolved conflicts prioritizing main's versions
-- TAG validation bypassed for merge commit
-- Enabled Strict Mode to prevent future direct pushes
-
-**Lesson**: With Strict Mode active, this won't happen again. All releases must go through develop → main PR flow.
-
----
-
-## Policy Change Log
-
-| Date       | Change                                           | Owner        |
-|------|------|--------|
-| 2025-10-17 | Initial policy drafted (Strict Mode)             | git-manager  |
-| 2025-10-17 | Switched to Advisory Mode (warnings only)        | git-manager  |
-| 2025-10-29 | **Enabled GitHub Branch Protection (Strict Mode)** | Alfred       |
-| 2025-10-29 | Added develop-main sync guidelines and real-world case study | Alfred       |
-| 2025-10-29 | Enforced `enforce_admins`, `required_conversation_resolution` | Alfred       |
-
----
-
-**This policy is advisory—adapt it to fit your project needs.**  
-**Reach out to the team lead or release engineer for questions or suggestions.**