moai-adk 0.5.8__py3-none-any.whl → 0.6.1__py3-none-any.whl

moai_adk/__main__.py

@@ -38,7 +38,7 @@ def show_logo() -> None:
     console.print(__version__, style="cyan bold")
     console.print()
     console.print("  Tip: Run ", style="yellow", end="")
-    console.print("python -m moai_adk --help", style="cyan", end="")
+    console.print("uv run moai-adk --help", style="cyan", end="")
     console.print(" to see available commands", style="yellow")
 
 

moai_adk/templates/.moai/memory/CONFIG-SCHEMA.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/.moai/memory/gitflow-protection-policy.md

@@ -0,0 +1,220 @@
+# GitFlow Advisory Policy
+
+**Document ID**: @DOC:GITFLOW-POLICY-001  
+**Published**: 2025-10-17  
+**Status**: Advisory (recommended, not enforced)  
+**Scope**: Personal and Team modes
+
+---
+
+## Overview
+
+MoAI-ADK **recommends** a GitFlow-inspired workflow. This policy shares best practices while letting teams adapt them as needed.
+
+## Key Recommendations
+
+### 1. Main Branch Access (Recommended)
+
+| Recommendation | Summary | Enforcement |
+|----------------|---------|-------------|
+| **Merge via develop** | Prefer merging `develop` into `main` | Advisory ⚠️ |
+| **Feature branches off develop** | Branch from `develop` and raise PRs back to `develop` | Advisory ⚠️ |
+| **Release process** | Release flow: `develop` → `main` (release engineer encouraged) | Advisory ⚠️ |
+| **Force push** | Warn when force-pushing, but allow it | Warning ⚠️ |
+| **Direct push** | Warn on direct pushes to `main`, but allow them | Warning ⚠️ |
+
+### 2. Git Workflow (Recommended)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                RECOMMENDED GITFLOW                      │
+└─────────────────────────────────────────────────────────┘
+
+        develop (recommended base branch)
+          ↑     ↓
+    ┌─────────────────┐
+    │                 │
+    │   developer work │
+    │                 │
+    ↓                 ↑
+feature/SPEC-{ID}   [PR: feature -> develop]
+                     [code review + approval]
+                     [Merge to develop]
+
+    develop (stable)
+         ↓
+         │   (release manager prepares)
+         ↓
+    [PR: develop -> main]
+    [CI/CD validation]
+    [tag creation]
+         ↓
+       main (release)
+```
+
+**Flexibility**: Direct pushes to `main` are still possible, but the workflow above is preferred.
+
+## 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 (Legacy, Currently Disabled)
+
+- ❌ Block direct pushes to `main`
+- ❌ Block force pushes
+- ❌ Block merges into `main` from any branch other than `develop`
+
+### Advisory Mode (Active, v0.3.5+)
+
+- ⚠️ Warn but allow direct pushes to `main`
+- ⚠️ Warn but allow force pushes
+- ⚠️ Recommend best practices while preserving flexibility
+- ✅ Respect user judgment
+
+---
+
+## 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: To promote best practices while respecting contributor flexibility and judgment.
+
+---
+
+## 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  |
+
+---
+
+**This policy is advisory—adapt it to fit your project needs.**  
+**Reach out to the team lead or release engineer for questions or suggestions.**

moai_adk/templates/.moai/memory/spec-metadata.md

@@ -0,0 +1,356 @@
+# SPEC Metadata Structure Guide
+
+> **MoAI-ADK SPEC Metadata Standard**
+>
+> Every SPEC document must follow this structure.
+
+---
+
+## 📋 Metadata Overview
+
+SPEC metadata contains **7 required fields** and **9 optional fields**.
+
+### Full Example
+
+```yaml
+---
+# Required Fields (7)
+id: AUTH-001                    # Unique SPEC ID
+version: 0.0.1                  # Semantic version (v0.0.1 = INITIAL, draft start)
+status: draft                   # draft|active|completed|deprecated
+created: 2025-09-15             # Creation date (YYYY-MM-DD)
+updated: 2025-09-15             # Last updated (YYYY-MM-DD; initially same as created)
+author: @Goos                   # Author (single GitHub handle)
+priority: high                  # low|medium|high|critical
+
+# Optional Fields – Classification/Meta
+category: security              # feature|bugfix|refactor|security|docs|perf
+labels:                         # Tags for search and grouping
+  - authentication
+  - jwt
+
+# Optional Fields – Relationships (Dependency Graph)
+depends_on:                     # SPECs this one depends on (optional)
+  - USER-001
+blocks:                         # SPECs blocked by this one (optional)
+  - AUTH-002
+related_specs:                  # Related SPECs (optional)
+  - TOKEN-002
+related_issue: "https://github.com/modu-ai/moai-adk/issues/123"
+
+# Optional Fields – Scope/Impact
+scope:
+  packages:                     # Impacted packages
+    - src/core/auth
+  files:                        # Key files (optional)
+    - auth-service.ts
+    - jwt-manager.ts
+---
+```
+
+---
+
+## Required Fields
+
+### 1. `id` – Unique SPEC Identifier
+- **Type**: string
+- **Format**: `<DOMAIN>-<NUMBER>`
+- **Examples**: `AUTH-001`, `INSTALLER-SEC-001`
+- **Rules**:
+  - Immutable once assigned
+  - Use three digits (001–999)
+  - Domain in uppercase; hyphens allowed
+  - Directory name: `.moai/specs/SPEC-{ID}/` (e.g., `.moai/specs/SPEC-AUTH-001/`)
+
+### 2. `version` – Semantic Version
+- **Type**: string (`MAJOR.MINOR.PATCH`)
+- **Default**: `0.0.1` (all SPECs start here, status: draft)
+- **Version Lifecycle**:
+  - **v0.0.1**: INITIAL – SPEC first draft (status: draft)
+  - **v0.0.x**: Draft refinements (increment PATCH when editing the SPEC)
+  - **v0.1.0**: TDD implementation complete (status: completed, updated via `/alfred:3-sync`)
+  - **v0.1.x**: Bug fixes or doc improvements (PATCH increment)
+  - **v0.x.0**: Feature additions or major enhancements (MINOR increment)
+  - **v1.0.0**: Stable release (production ready, explicit stakeholder approval required)
+
+### 3. `status` – Progress State
+- **Type**: enum
+- **Values**:
+  - `draft`: Authoring in progress
+  - `active`: Implementation underway
+  - `completed`: Implementation finished
+  - `deprecated`: Planned for retirement
+
+### 4. `created` – Creation Date
+- **Type**: date string
+- **Format**: `YYYY-MM-DD`
+- **Example**: `2025-10-06`
+
+### 5. `updated` – Last Modified Date
+- **Type**: date string
+- **Format**: `YYYY-MM-DD`
+- **Rule**: Update whenever the SPEC content changes.
+
+### 6. `author` – Primary Author
+- **Type**: string
+- **Format**: `@{GitHub ID}`
+- **Example**: `@Goos`
+- **Rules**:
+  - Single value only (no `authors` array)
+  - Prefix the GitHub handle with `@`
+  - Additional contributors belong in the HISTORY section
+
+### 7. `priority` – Work Priority
+- **Type**: enum
+- **Values**:
+  - `critical`: Immediate attention (security, severe defects)
+  - `high`: Major feature work
+  - `medium`: Enhancements
+  - `low`: Optimizations or documentation
+
+---
+
+## Optional Fields
+
+### Classification / Meta
+
+#### 8. `category` – Change Type
+- **Type**: enum
+- **Values**:
+  - `feature`: New functionality
+  - `bugfix`: Defect resolution
+  - `refactor`: Structural improvements
+  - `security`: Security enhancements
+  - `docs`: Documentation updates
+  - `perf`: Performance optimizations
+
+#### 9. `labels` – Classification Tags
+- **Type**: array of strings
+- **Purpose**: Search, filtering, grouping
+- **Example**:
+  ```yaml
+  labels:
+    - installer
+    - template
+    - security
+  ```
+
+### Relationship Fields (Dependency Graph)
+
+#### 10. `depends_on` – Required SPECs
+- **Type**: array of strings
+- **Meaning**: SPECs that must be completed first
+- **Example**:
+  ```yaml
+  depends_on:
+    - USER-001
+    - AUTH-001
+  ```
+- **Use Case**: Determines execution order and parallelization.
+
+#### 11. `blocks` – Blocked SPECs
+- **Type**: array of strings
+- **Meaning**: SPECs that cannot proceed until this one is resolved
+- **Example**:
+  ```yaml
+  blocks:
+    - PAYMENT-003
+  ```
+
+#### 12. `related_specs` – Associated SPECs
+- **Type**: array of strings
+- **Meaning**: Related items without direct dependencies
+- **Example**:
+  ```yaml
+  related_specs:
+    - TOKEN-002
+    - SESSION-001
+  ```
+
+#### 13. `related_issue` – Linked GitHub Issue
+- **Type**: string (URL)
+- **Format**: Full GitHub issue URL
+- **Example**:
+  ```yaml
+  related_issue: "https://github.com/modu-ai/moai-adk/issues/123"
+  ```
+
+### Scope Fields (Impact Analysis)
+
+#### 14. `scope.packages` – Impacted Packages
+- **Type**: array of strings
+- **Meaning**: Packages or modules touched by the SPEC
+- **Example**:
+  ```yaml
+  scope:
+    packages:
+      - moai-adk-ts/src/core/installer
+      - moai-adk-ts/src/core/git
+  ```
+
+#### 15. `scope.files` – Key Files
+- **Type**: array of strings
+- **Meaning**: Primary files involved (for reference)
+- **Example**:
+  ```yaml
+  scope:
+    files:
+      - template-processor.ts
+      - template-security.ts
+  ```
+
+---
+
+## Metadata Validation
+
+### Required Field Checks
+```bash
+# Verify that every SPEC includes the required fields
+rg "^(id|version|status|created|updated|author|priority):" .moai/specs/SPEC-*/spec.md
+
+# Identify SPECs missing the priority field
+rg -L "^priority:" .moai/specs/SPEC-*/spec.md
+```
+
+### Format Checks
+```bash
+# Ensure the author field uses @Handle format
+rg "^author: @[A-Z]" .moai/specs/SPEC-*/spec.md
+
+# Ensure the version field follows 0.x.y
+rg "^version: 0\.\d+\.\d+" .moai/specs/SPEC-*/spec.md
+```
+
+---
+
+## Migration Guide
+
+### Updating Existing SPECs
+
+#### 1. Add the `priority` Field
+Add it if missing:
+```yaml
+priority: medium  # or low|high|critical
+```
+
+#### 2. Normalize the `author` Field
+- `authors: ["@goos"]` → `author: @Goos`
+- Convert lowercase handles to the canonical casing.
+
+#### 3. Add Optional Fields (Recommended)
+```yaml
+category: refactor
+labels:
+  - code-quality
+  - maintenance
+```
+
+### Updating config.json for Language Support (v0.4.2+)
+
+**Background**: MoAI-ADK v0.4.2 introduces conversation language selection in `/alfred:0-project`. Existing projects need to add language metadata to `.moai/config.json`.
+
+#### Migration Steps
+
+**For Existing Projects** (before v0.4.2):
+
+Current config.json structure:
+```json
+{
+  "project": {
+    "locale": "en",
+    "mode": "personal",
+    "language": "python"
+  }
+}
+```
+
+**Updated Structure** (v0.4.2+):
+```json
+{
+  "project": {
+    "locale": "en",
+    "mode": "personal",
+    "language": "python",
+    "conversation_language": "en",
+    "conversation_language_name": "English",
+    "codebase_languages": ["python"]
+  }
+}
+```
+
+#### New Fields
+
+| Field | Type | Required | Description | Example |
+|-------|------|----------|-------------|---------|
+| `conversation_language` | string (ISO 639-1 code) | ✅ Yes | Two-letter language code for Alfred dialogs | `"ko"`, `"en"`, `"ja"`, `"zh"` |
+| `conversation_language_name` | string | ✅ Yes | Display name of conversation language | `"Korean"`, `"English"` |
+| `codebase_languages` | array of strings | ✅ Yes | List of programming languages detected | `["python"]`, `["typescript", "python"]` |
+
+#### Manual Update Process
+
+1. Open `.moai/config.json`
+2. Add the three new fields under `project`:
+   ```json
+   "conversation_language": "en",
+   "conversation_language_name": "English",
+   "codebase_languages": ["python"]
+   ```
+3. Save and commit:
+   ```bash
+   git add .moai/config.json
+   git commit -m "chore: add language metadata to config.json for v0.4.2+"
+   ```
+
+#### Automated Update (via `/alfred:0-project`)
+
+Running `/alfred:0-project` on an existing project will:
+1. Detect current language settings
+2. Add new fields automatically
+3. Preserve existing values
+
+**No manual action required if running `/alfred:0-project` after upgrade.**
+
+#### Field Mapping (Legacy → New)
+
+| Old Field | New Field | Migration Rule |
+|-----------|-----------|-----------------|
+| `locale` | `conversation_language` | Keep as-is (or run `/alfred:0-project` to re-select) |
+| (none) | `conversation_language_name` | Auto-populate from locale mapping |
+| `language` | `codebase_languages` | Wrap in array: `"python"` → `["python"]` |
+
+#### Backward Compatibility
+
+- ✅ Projects without new fields will continue working
+- ⚠️ New language features (multilingual documentation) unavailable without migration
+- ✅ `/alfred:0-project` automatically migrates on next run
+- ✅ Auto-detection will prefer new fields if present
+
+---
+
+## Design Principles
+
+### 1. DRY (Don't Repeat Yourself)
+- ❌ **Remove**: the `reference` field (every SPEC referenced the same master plan)
+- ✅ **Instead**: document project-level resources in README.md
+
+### 2. Context-Aware
+- Include only the necessary context.
+- Use optional fields only when they add value.
+
+### 3. Traceable
+- Use `depends_on`, `blocks`, and `related_specs` to map dependencies.
+- Automated tooling can detect cyclic references.
+
+### 4. Maintainable
+- Every field must be machine-verifiable.
+- Maintain consistent formatting for easy parsing.
+
+### 5. Simple First
+- Keep complexity low.
+- Limit to 7 required + 9 optional fields.
+- Expand gradually when justified.
+
+---
+
+**Last Updated**: 2025-10-06  
+**Author**: @Alfred

{moai_adk-0.5.8.dist-info → moai_adk-0.6.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.5.8
+Version: 0.6.1
 Summary: MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0
 Project-URL: Homepage, https://github.com/modu-ai/moai-adk
 Project-URL: Repository, https://github.com/modu-ai/moai-adk
@@ -23,6 +23,7 @@ Requires-Dist: click>=8.1.0
 Requires-Dist: gitpython>=3.1.45
 Requires-Dist: packaging>=21.0
 Requires-Dist: pyfiglet>=1.0.2
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: rich>=13.0.0
 Provides-Extra: dev

{moai_adk-0.5.8.dist-info → moai_adk-0.6.1.dist-info}/RECORD

@@ -1,5 +1,5 @@
 moai_adk/__init__.py,sha256=8E7tMBsxNR-EFqDY241RCJlSZEdCSigIbek2CiOzMBs,359
-moai_adk/__main__.py,sha256=vDQDlH6B9Pvp0dZBopngY1ctWubDdkB7uRyDFEjBxmM,2424
+moai_adk/__main__.py,sha256=uo6p-EzHYCetlU3gGxGasiIkwGq6wlzag7RYtzieoJI,2421
 moai_adk/cli/__init__.py,sha256=tidIaJnd4Pje_5QYRq7OvRRst4T3kaPlkw5QcPQ3l1Y,135
 moai_adk/cli/main.py,sha256=mHACHi27AP2N7fg7zhzOo1tlF1Jrlw1_AcbxMfpGLVE,306
 moai_adk/cli/commands/__init__.py,sha256=TrAIWcJRGXh1mY8itSzWm-W0nnybzQIFOuh6oksKWO0,680
@@ -259,19 +259,22 @@ moai_adk/templates/.moai/config.json,sha256=0DZ9zK3wUD2lRfeqX93tYJz5Pb_h7DV4k2wy
 moai_adk/templates/.moai/memory/CLAUDE-AGENTS-GUIDE.md,sha256=37Qj5DYcyUniLM1g8IU7UWFI_16tutZrcAkJc4E5i20,15876
 moai_adk/templates/.moai/memory/CLAUDE-PRACTICES.md,sha256=Tf3q68X1DiA3MkIBYu7AMXoeparYrDRpyqVI5Nw92OY,12653
 moai_adk/templates/.moai/memory/CLAUDE-RULES.md,sha256=S9GODGRzwwleOmROVtBDa471Ok5NyQLWIkaO_4peHhU,19783
+moai_adk/templates/.moai/memory/CONFIG-SCHEMA.md,sha256=XmvogEnGedRItVc9OABKr4lDNEZhcKZQ3Qa6KlfxE3E,12477
 moai_adk/templates/.moai/memory/DEVELOPMENT-GUIDE.md,sha256=SAcue1J5-DEJpygDnTgp_ex-ok2E4lbcykBuBiC7tGs,14534
 moai_adk/templates/.moai/memory/GITFLOW-PROTECTION-POLICY.md,sha256=tm2ZOmNMvomAhh4_AGTUNjmSsc-eKzo1SGshojx2QL0,6228
 moai_adk/templates/.moai/memory/SKILLS-DESCRIPTION-POLICY.md,sha256=uMEFi6uojnpO_MGGtwhakYQzVF2yzVV9ZzfQe5tB0Hk,7823
 moai_adk/templates/.moai/memory/SPEC-METADATA.md,sha256=Ha4ATMxyH2PgQdVbS1fYwVH0PnIkfqk4hfuB5ksMFFk,9702
 moai_adk/templates/.moai/memory/config-schema.md,sha256=XmvogEnGedRItVc9OABKr4lDNEZhcKZQ3Qa6KlfxE3E,12477
+moai_adk/templates/.moai/memory/gitflow-protection-policy.md,sha256=tm2ZOmNMvomAhh4_AGTUNjmSsc-eKzo1SGshojx2QL0,6228
+moai_adk/templates/.moai/memory/spec-metadata.md,sha256=Ha4ATMxyH2PgQdVbS1fYwVH0PnIkfqk4hfuB5ksMFFk,9702
 moai_adk/templates/.moai/project/product.md,sha256=IrRSqhu0o5KNfn453DUWoUKzdoO3m6013iYCwaHYCxM,5166
 moai_adk/templates/.moai/project/structure.md,sha256=YWZ4ggmfzveKx8SQGFQWXdDUh5mxOLkEyy5yVdR3Rn0,4791
 moai_adk/templates/.moai/project/tech.md,sha256=REecMv8wOvutt-pQZ5nlGk5YdReTan7AHcKJ2Yes6RM,5758
 moai_adk/utils/__init__.py,sha256=VnVfQzzKHvKw4bNdEw5xdscnRQYFrnr-v_TOBr3naPs,225
 moai_adk/utils/banner.py,sha256=znppKd5yo-tTqgyhgPVJjstrTrfcy_v3X1_RFQxP4Fk,1878
 moai_adk/utils/logger.py,sha256=g-m07PGKjK2bKRIInfSn6m-024Bedai-pV_WjZKDeu8,5064
-moai_adk-0.5.8.dist-info/METADATA,sha256=rEHgIIkbDREkZxp5YZ2l4X1B7dTHTLK_7NwI6lEttHM,67983
-moai_adk-0.5.8.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-moai_adk-0.5.8.dist-info/entry_points.txt,sha256=P9no1794UipqH72LP-ltdyfVd_MeB1WKJY_6-JQgV3U,52
-moai_adk-0.5.8.dist-info/licenses/LICENSE,sha256=M1M2b07fWcSWRM6_P3wbZKndZvyfHyYk_Wu9bS8F7o8,1069
-moai_adk-0.5.8.dist-info/RECORD,,
+moai_adk-0.6.1.dist-info/METADATA,sha256=IX0tIPlVvj4lXEA23-HJc6PwOfRaVlHuI9P81gkOPvo,68010
+moai_adk-0.6.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+moai_adk-0.6.1.dist-info/entry_points.txt,sha256=P9no1794UipqH72LP-ltdyfVd_MeB1WKJY_6-JQgV3U,52
+moai_adk-0.6.1.dist-info/licenses/LICENSE,sha256=M1M2b07fWcSWRM6_P3wbZKndZvyfHyYk_Wu9bS8F7o8,1069
+moai_adk-0.6.1.dist-info/RECORD,,