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

moai_adk/templates/.claude/skills/moai-alfred-agent-guide/examples.md

@@ -0,0 +1,62 @@
+# Agent Selection Examples
+
+## Example 1: New Feature Request
+
+**User**: "Add two-factor authentication"
+
+**Decision Tree**:
+```
+Task = Feature Implementation
+  ↓
+Create SPEC first? → YES
+Invoke: spec-builder
+  ↓
+Write Tests? → YES
+Invoke: tdd-implementer
+  ↓
+Need Code Review? → YES
+Invoke: quality-gate + Skill("moai-foundation-trust")
+  ↓
+Update Documentation? → YES
+Invoke: doc-syncer
+```
+
+**Result**: Proper agent sequence avoids rework
+
+---
+
+## Example 2: Bug Fix Triage
+
+**Error**: "TypeError: undefined is not a function"
+
+**Agent Sequence**:
+1. Invoke: debug-helper
+   - Analyze stack trace
+   - Identify root cause
+2. Invoke: tdd-implementer
+   - Write regression test
+   - Fix implementation
+3. Invoke: git-manager
+   - Commit with @TAG
+
+---
+
+## Example 3: Large Codebase Exploration
+
+**Task**: "How is authentication implemented?"
+
+✅ Correct:
+```
+Invoke: Explore(prompt="Find auth flow, entry points, models")
+Result: Clear architecture map
+```
+
+❌ Wrong:
+```
+Manual grep for 20+ files
+Result: Bloated context, still confused
+```
+
+---
+
+Learn more in `reference.md` for complete decision tree and multi-agent patterns.

moai_adk/templates/{.moai/memory/CLAUDE-AGENTS-GUIDE.md → .claude/skills/moai-alfred-agent-guide/reference.md}

@@ -68,6 +68,40 @@ The **code-builder pipeline** runs two Sonnet specialists in sequence: **impleme
 
 ---
 
+## Expert Agents (Proactively Triggered by SPEC Keywords)
+
+| Expert Agent            | Model  | Specialty                                                                           | Trigger Keywords                                                                                   | Trigger Source      |
+| ----------------------- | ------ | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------- |
+| **backend-expert** 🔧   | Sonnet | Backend architecture, API design, database schema, microservices, authentication    | 'backend', 'api', 'server', 'database', 'microservice', 'deployment', 'authentication'            | implementation-planner |
+| **frontend-expert** 💻  | Sonnet | Frontend architecture, component design, state management, UI/UX implementation     | 'frontend', 'ui', 'page', 'component', 'client-side', 'browser', 'web interface'                  | implementation-planner |
+| **devops-expert** 🚀    | Sonnet | DevOps strategy, deployment automation, containerization, CI/CD, cloud infrastructure | 'deployment', 'docker', 'kubernetes', 'ci/cd', 'pipeline', 'infrastructure', 'railway', 'vercel', 'aws' | implementation-planner |
+| **ui-ux-expert** 🎨     | Sonnet | UI/UX design, accessibility (WCAG 2.1 AA/AAA), design systems, Figma MCP, design-to-code | 'design', 'ux', 'ui', 'accessibility', 'a11y', 'user experience', 'wireframe', 'prototype', 'design system', 'figma', 'user research', 'persona', 'journey map' | implementation-planner |
+
+### How Expert Agents Work
+
+1. **Automatic Keyword Detection**: When `implementation-planner` analyzes a SPEC, it scans for expert trigger keywords
+2. **Proactive Delegation**: If keywords match, `implementation-planner` automatically invokes the relevant expert agent(s)
+3. **Expert Consultation**: Each expert provides domain-specific architecture guidance, technology recommendations, and risk analysis
+4. **Integration**: Expert feedback is integrated into the implementation plan and tagged with `@EXPERT:DOMAIN` for traceability
+
+### Example: Full-Stack Authentication SPEC
+
+```
+SPEC Keywords: 'api', 'authentication', 'design', 'accessibility'
+
+→ Trigger backend-expert (for API & auth architecture)
+→ Trigger ui-ux-expert (for login UI & accessibility)
+
+Result:
+@SPEC:AUTH-001 | @EXPERT:BACKEND | @EXPERT:UIUX
+
+Implementation Plan includes:
+- Backend: JWT token strategy, rate limiting, audit logging
+- UI/UX: Accessible login form (WCAG 2.1 AA), error messaging
+```
+
+---
+
 ## Zero-project Specialists
 
 | Sub-agent                  | Model  | Focus                                                       | Trigger                         |

moai_adk/templates/.claude/skills/moai-alfred-config-schema/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: moai-alfred-config-schema
+description: ".moai/config.json official schema documentation, structure validation, project metadata, language settings, and configuration migration guide. Use when setting up project configuration or understanding config.json structure."
+allowed-tools: "Read, Grep"
+---
+
+## What It Does
+
+`.moai/config.json` 파일의 공식 스키마와 각 필드의 목적, 유효한 값, 마이그레이션 규칙을 정의합니다.
+
+## When to Use
+
+- ✅ Project 초기화 후 config.json 설정
+- ✅ config.json 스키마 이해
+- ✅ Language settings, git strategy, TAG configuration 변경
+- ✅ Legacy config 마이그레이션
+
+## Schema Overview
+
+```json
+{
+  "version": "0.7.0",
+  "project": {
+    "name": "ProjectName",
+    "codebase_language": "python",
+    "conversation_language": "ko",
+    "conversation_language_name": "Korean"
+  },
+  "language": {
+    "conversation_language": "ko",
+    "conversation_language_name": "Korean"
+  },
+  "git": {
+    "strategy": "github-pr",
+    "main_branch": "main",
+    "protected": true
+  },
+  "tag": {
+    "prefix_style": "DOMAIN-###"
+  }
+}
+```
+
+## Top-Level Sections
+
+- **version**: Configuration version (do not edit)
+- **project**: Name, codebase language, conversation language
+- **language**: Multi-language support settings
+- **git**: GitHub workflow strategy
+- **tag**: TAG system configuration
+
+---
+
+Learn more in `reference.md` for complete schema reference, validation rules, and migration examples.
+
+**Related Skills**: moai-alfred-dev-guide, moai-foundation-specs

moai_adk/templates/.claude/skills/moai-alfred-config-schema/examples.md

@@ -0,0 +1,28 @@
+# Config.json Examples
+
+## Example: Korean Project Setup
+
+```json
+{
+  "version": "0.7.0",
+  "project": {
+    "name": "MyKoreanProject",
+    "codebase_language": "python",
+    "conversation_language": "ko",
+    "conversation_language_name": "Korean"
+  },
+  "language": {
+    "conversation_language": "ko",
+    "conversation_language_name": "Korean"
+  },
+  "git": {
+    "strategy": "github-pr",
+    "main_branch": "main",
+    "protected": true
+  }
+}
+```
+
+---
+
+Learn more in `reference.md`.

moai_adk/templates/.claude/skills/moai-alfred-config-schema/reference.md

@@ -0,0 +1,444 @@
+# MoAI-ADK config.json Schema Documentation
+
+> **Purpose**: This document defines the official schema structure for `.moai/config.json` file, which serves as the single source of truth for all MoAI-ADK project configuration.
+
+---
+
+## 📋 Schema Overview
+
+The `.moai/config.json` file contains all project-level configuration for MoAI-ADK, including:
+- Project metadata and settings
+- User preferences (language, nickname)
+- Git workflow strategies
+- TAG system configuration
+- Constitution principles
+
+---
+
+## 🏗️ Schema Structure
+
+### Top-Level Sections
+
+```json
+{
+  "_meta": { /* Metadata about the config file itself */ },
+  "moai": { /* MoAI-ADK version info */ },
+  "project": { /* Project-specific settings */ },
+  "user": { /* User preferences */ },
+  "constitution": { /* Development principles */ },
+  "git_strategy": { /* Git workflow configuration */ },
+  "pipeline": { /* Command pipeline settings */ },
+  "tags": { /* TAG system configuration */ }
+}
+```
+
+---
+
+## 📖 Section Definitions
+
+### 1. `_meta` Section
+
+**Purpose**: Internal metadata for config structure tracking and TAG traceability.
+
+**Schema**:
+```json
+{
+  "_meta": {
+    "@CODE:CONFIG-STRUCTURE-001": "@DOC:JSON-CONFIG-001",
+    "@SPEC:PROJECT-CONFIG-001": "@SPEC:MOAI-CONFIG-001"
+  }
+}
+```
+
+**Fields**:
+- `@CODE:*`: TAG references to code implementation
+- `@SPEC:*`: TAG references to specification documents
+
+---
+
+### 2. `moai` Section
+
+**Purpose**: Track MoAI-ADK package version for compatibility checks.
+
+**Schema**:
+```json
+{
+  "moai": {
+    "version": "0.4.6"
+  }
+}
+```
+
+**Fields**:
+- `version` (string, required): MoAI-ADK version in SemVer format (e.g., "0.4.6")
+
+---
+
+### 3. `project` Section
+
+**Purpose**: Core project settings including name, mode, language preferences, and optimization status.
+
+**Schema**:
+```json
+{
+  "project": {
+    "name": "MoAI-ADK",
+    "description": "MoAI-Agentic Development Kit",
+    "mode": "personal",
+    "locale": "ko",
+    "conversation_language": "ko",
+    "conversation_language_name": "한국어",
+    "language": "python",
+    "moai_adk_version": "0.4.6",
+    "initialized": true,
+    "optimized": true,
+    "optimized_at": "2025-10-22T12:45:00Z",
+    "created_at": "2025-10-21 23:59:19"
+  }
+}
+```
+
+**Fields**:
+- `name` (string, required): Project name
+- `description` (string, optional): Brief project description
+- `mode` (enum, required): Project mode — `"personal"` | `"team"`
+- `locale` (string, required): System locale code (e.g., `"ko"`, `"en"`, `"ja"`)
+- `conversation_language` (string, required): Language code for all Alfred dialogs and documentation (e.g., `"ko"`, `"en"`, `"ja"`, `"zh"`)
+- `conversation_language_name` (string, required): Display name of conversation language (e.g., `"한국어"`, `"English"`)
+- `language` (string, required): Primary codebase language (e.g., `"python"`, `"typescript"`)
+- `moai_adk_version` (string, required): MoAI-ADK version this project was initialized with
+- `initialized` (boolean, required): Whether project initialization completed
+- `optimized` (boolean, required): Whether template optimization completed
+- `optimized_at` (string, optional): ISO 8601 timestamp of optimization completion
+- `created_at` (string, required): Project creation timestamp
+
+**Notes**:
+- `conversation_language` is set during `/alfred:0-project` STEP 0.1
+- `language` is auto-detected during `/alfred:0-project` STEP 1 or can be manually specified
+
+---
+
+### 4. `user` Section (NEW in v0.4.6)
+
+**Purpose**: User-specific preferences for personalized Alfred experience.
+
+**Schema**:
+```json
+{
+  "user": {
+    "nickname": "GOOS오라버니"
+  }
+}
+```
+
+**Fields**:
+- `nickname` (string, required): User's chosen nickname for personalized communication
+  - Length: 1-50 characters
+  - Allows emoji, spaces, and special characters
+  - Set during `/alfred:0-project` STEP 0.2
+  - Used by all sub-agents to address the user (e.g., "안녕하세요, GOOS오라버니님!")
+  - Displayed in `CLAUDE.md` under "## 프로젝트 정보 | Project Information"
+
+**Usage**:
+- Alfred and all sub-agents receive `user_nickname` as a context parameter
+- Language-specific honorifics are applied automatically (e.g., "님" in Korean)
+- Enhances user experience by personalizing all interactions
+
+---
+
+### 5. `constitution` Section
+
+**Purpose**: Define development principles and quality gates enforced by MoAI-ADK.
+
+**Schema**:
+```json
+{
+  "constitution": {
+    "enforce_tdd": true,
+    "require_tags": true,
+    "test_coverage_target": 85,
+    "simplicity_threshold": 5,
+    "principles": {
+      "simplicity": {
+        "max_projects": 5,
+        "notes": "Default recommendation. Adjust in .moai/config.json or via SPEC/ADR with documented rationale based on project size."
+      }
+    }
+  }
+}
+```
+
+**Fields**:
+- `enforce_tdd` (boolean, required): Whether TDD workflow is mandatory
+- `require_tags` (boolean, required): Whether @TAG annotations are required
+- `test_coverage_target` (integer, required): Minimum test coverage percentage (default: 85)
+- `simplicity_threshold` (integer, required): Max number of concurrent projects (default: 5)
+- `principles` (object, optional): Additional principle definitions
+
+---
+
+### 6. `git_strategy` Section
+
+**Purpose**: Configure Git workflow automation based on project mode.
+
+**Schema**:
+```json
+{
+  "git_strategy": {
+    "personal": {
+      "auto_checkpoint": "event-driven",
+      "checkpoint_events": ["delete", "refactor", "merge", "script", "critical-file"],
+      "checkpoint_type": "local-branch",
+      "max_checkpoints": 10,
+      "cleanup_days": 7,
+      "push_to_remote": false,
+      "auto_commit": true,
+      "branch_prefix": "feature/",
+      "develop_branch": "develop",
+      "main_branch": "main"
+    },
+    "team": {
+      "use_gitflow": true,
+      "auto_pr": true,
+      "draft_pr": true,
+      "feature_prefix": "feature/SPEC-",
+      "develop_branch": "develop",
+      "main_branch": "main"
+    }
+  }
+}
+```
+
+**Personal Mode Fields**:
+- `auto_checkpoint` (enum): `"event-driven"` | `"manual"` | `"disabled"`
+- `checkpoint_events` (array): List of events triggering auto-checkpoint
+- `checkpoint_type` (enum): `"local-branch"` | `"git-stash"` | `"backup-dir"`
+- `max_checkpoints` (integer): Max number of checkpoints to retain
+- `cleanup_days` (integer): Days before old checkpoints are removed
+- `push_to_remote` (boolean): Whether to push checkpoints to remote
+- `auto_commit` (boolean): Auto-commit changes after TDD cycles
+- `branch_prefix` (string): Prefix for feature branches
+- `develop_branch` (string): Name of develop branch
+- `main_branch` (string): Name of main/production branch
+
+**Team Mode Fields**:
+- `use_gitflow` (boolean): Enable GitFlow branching strategy
+- `auto_pr` (boolean): Auto-create PR after feature completion
+- `draft_pr` (boolean): Create PRs in draft mode by default
+- `feature_prefix` (string): Prefix for feature branches (includes SPEC ID)
+- `develop_branch` (string): Name of develop branch
+- `main_branch` (string): Name of main/production branch
+
+---
+
+### 7. `pipeline` Section
+
+**Purpose**: Define available Alfred commands and track current workflow stage.
+
+**Schema**:
+```json
+{
+  "pipeline": {
+    "available_commands": [
+      "/alfred:0-project",
+      "/alfred:1-plan",
+      "/alfred:2-run",
+      "/alfred:3-sync"
+    ],
+    "current_stage": "initialized"
+  }
+}
+```
+
+**Fields**:
+- `available_commands` (array, required): List of available Alfred commands
+- `current_stage` (string, required): Current workflow stage (e.g., `"initialized"`, `"planning"`, `"building"`, `"syncing"`)
+
+---
+
+### 8. `tags` Section
+
+**Purpose**: Configure TAG system behavior and storage policy.
+
+**Schema**:
+```json
+{
+  "tags": {
+    "storage_type": "code_scan",
+    "auto_sync": true,
+    "categories": ["REQ", "DESIGN", "TASK", "TEST", "FEATURE", "API", "UI", "DATA"],
+    "code_scan_policy": {
+      "no_intermediate_cache": true,
+      "realtime_validation": true,
+      "scan_tools": ["rg", "grep"],
+      "scan_command": "rg '@TAG' -n",
+      "philosophy": "The source of truth for TAGs lives in the code itself"
+    }
+  }
+}
+```
+
+**Fields**:
+- `storage_type` (enum, required): `"code_scan"` | `"registry_file"`
+- `auto_sync` (boolean, required): Auto-sync TAGs during `/alfred:3-sync`
+- `categories` (array, required): List of valid TAG categories
+- `code_scan_policy` (object, required): Configuration for code-first TAG scanning
+  - `no_intermediate_cache` (boolean): Never use intermediate TAG cache files
+  - `realtime_validation` (boolean): Validate TAGs on every operation
+  - `scan_tools` (array): Tools used for TAG scanning (e.g., `["rg", "grep"]`)
+  - `scan_command` (string): Command to scan for TAGs
+  - `philosophy` (string): Description of TAG philosophy
+
+---
+
+## 🔄 Schema Evolution
+
+### Version History
+
+| Version | Date       | Changes                                                |
+| ------- | ---------- | ------------------------------------------------------ |
+| v0.4.6  | 2025-10-23 | Added `user` section with `nickname` field             |
+| v0.4.2  | 2025-10-22 | Added `conversation_language` and `language_name` fields |
+| v0.4.0  | 2025-10-20 | Initial schema documentation                           |
+
+### Migration Guide
+
+**From v0.4.5 → v0.4.6**:
+- Add `user` section with `nickname` field
+- No breaking changes; existing configs remain compatible
+
+**Example Migration**:
+```json
+// Before (v0.4.5)
+{
+  "project": {
+    "conversation_language": "ko",
+    "conversation_language_name": "한국어"
+  }
+}
+
+// After (v0.4.6)
+{
+  "project": {
+    "conversation_language": "ko",
+    "conversation_language_name": "한국어"
+  },
+  "user": {
+    "nickname": "GOOS오라버니"
+  }
+}
+```
+
+---
+
+## 📚 Related Documentation
+
+- **Template Processing**: `/src/moai_adk/cli/template_processor.py`
+- **Project Initialization**: `/.claude/commands/alfred/0-project.md`
+- **project-manager Agent**: `/.claude/agents/alfred/project-manager.md`
+- **CLAUDE.md Template**: `/src/moai_adk/templates/CLAUDE.md`
+
+---
+
+## ✅ Validation Rules
+
+### Required Fields per Section
+
+**Minimum Valid Config**:
+```json
+{
+  "moai": {
+    "version": "0.4.6"
+  },
+  "project": {
+    "name": "MyProject",
+    "mode": "personal",
+    "locale": "en",
+    "conversation_language": "en",
+    "conversation_language_name": "English",
+    "language": "python",
+    "initialized": true
+  },
+  "user": {
+    "nickname": "Developer"
+  },
+  "constitution": {
+    "enforce_tdd": true,
+    "require_tags": true,
+    "test_coverage_target": 85
+  },
+  "tags": {
+    "storage_type": "code_scan",
+    "auto_sync": true
+  }
+}
+```
+
+### Validation Checklist
+
+- [ ] `moai.version` matches installed package version
+- [ ] `project.mode` is either `"personal"` or `"team"`
+- [ ] `project.conversation_language` is a valid ISO 639-1 code
+- [ ] `user.nickname` length is between 1-50 characters
+- [ ] `constitution.test_coverage_target` is between 0-100
+- [ ] `tags.storage_type` is valid enum value
+- [ ] All required fields are present
+
+---
+
+## 🛠️ Usage Examples
+
+### Reading Config in Python
+
+```python
+import json
+from pathlib import Path
+
+def read_config():
+    config_path = Path(".moai/config.json")
+    with open(config_path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+config = read_config()
+user_nickname = config.get("user", {}).get("nickname", "Developer")
+conversation_language = config["project"]["conversation_language"]
+```
+
+### Updating User Nickname
+
+```python
+import json
+from pathlib import Path
+
+def update_user_nickname(new_nickname: str):
+    config_path = Path(".moai/config.json")
+
+    # Read existing config
+    with open(config_path, "r", encoding="utf-8") as f:
+        config = json.load(f)
+
+    # Update user section
+    if "user" not in config:
+        config["user"] = {}
+    config["user"]["nickname"] = new_nickname
+
+    # Write back
+    with open(config_path, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2, ensure_ascii=False)
+```
+
+---
+
+## 📝 Notes
+
+- **SSOT**: This config file is the single source of truth for all project settings
+- **No Duplication**: Never duplicate config values in code or other files
+- **Encoding**: Always use UTF-8 encoding to support international characters in nicknames and language names
+- **Validation**: Always validate config structure before reading values
+- **Migration**: When adding new fields, provide sensible defaults for backwards compatibility
+
+---
+
+**Last Updated**: 2025-10-23
+**Version**: v0.4.6
+**Maintainer**: cc-manager

moai_adk/templates/.claude/skills/moai-alfred-context-budget/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: moai-alfred-context-budget
+description: "Claude Code context window optimization strategies, JIT retrieval, progressive loading, memory file patterns, and cleanup practices. Use when optimizing context usage, managing large projects, or implementing efficient workflows."
+allowed-tools: "Read, Grep"
+---
+
+## What It Does
+
+Claude Code context budget (100K-200K tokens)의 효율적 관리 전략, progressive disclosure, JIT retrieval, memory file 구조화 방법을 제공합니다.
+
+## When to Use
+
+- ✅ Context limit 도달 위험성 있을 때
+- ✅ 대규모 프로젝트의 context 관리 필요
+- ✅ Session handoff 준비
+- ✅ Memory file 구조 설계/정리
+
+## Context Budget Overview
+
+```
+Total: 100K-200K tokens
+├── System Prompt: ~2K
+├── Tools & Instructions: ~5K
+├── Session History: ~30K
+├── Project Context: ~40K
+└── Available for Response: ~23K
+```
+
+## Progressive Disclosure Pattern
+
+1. **Metadata** (always): Skill name, description, triggers
+2. **Content** (on-demand): Full SKILL.md when invoked
+3. **Supporting** (JIT): Examples, templates when referenced
+
+## JIT Retrieval Principles
+
+- Pull only what you need for immediate step
+- Prefer `Explore` over manual file hunting
+- Cache critical insights for reuse
+- Remove unnecessary files regularly
+
+## Best Practices
+
+✅ DO:
+- Use Explore for large searches
+- Cache results in memory files
+- Keep memory files < 500 lines each
+- Update session-summary.md before task switches
+- Archive completed work
+
+❌ DON'T:
+- Load entire src/ directory upfront
+- Duplicate context between files
+- Store memory files outside `.moai/memory/`
+- Leave stale session notes (archive or delete)
+- Cache raw code (summarize instead)
+
+---
+
+Learn more in `reference.md` for detailed JIT strategy, memory patterns, context budget calculations, and management practices.
+
+**Related Skills**: moai-alfred-practices, moai-cc-memory