moai-adk 0.8.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

moai_adk/templates/.moai/memory/config-schema.md

@@ -1,444 +0,0 @@
-# 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

@@ -1,220 +0,0 @@
-# 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.**