moai-adk 0.5.6__tar.gz → 0.6.0__tar.gz

{moai_adk-0.5.6 → moai_adk-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.5.6
+Version: 0.6.0
 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
@@ -68,7 +68,6 @@ If you've **already installed it and want to understand the concepts**, we recom
 | What do Plan/Run/Sync commands do? | [Command Cheat Sheet](#command-cheat-sheet)                              |
 | What are SPEC, TDD, TAG?           | [5 Key Concepts](#5-key-concepts)                                        |
 | Tell me about agents/Skills        | [Sub-agents & Skills Overview](#sub-agents--skills-overview)             |
-| I want a 4-week hands-on project   | [Second Practice: Mini Kanban Board](#second-practice-mini-kanban-board) |
 | Want to dive deeper?               | [Additional Resources](#additional-resources)                            |
 
 ---
@@ -629,6 +628,119 @@ graph TD
 
 ---
 
+## SPEC GitHub Issue Automation
+
+MoAI-ADK now provides **automatic GitHub Issue synchronization** from SPEC documents, seamlessly integrating requirements with issue tracking in team mode.
+
+### How It Works
+
+When you create a SPEC document using `/alfred:1-plan` and push it to a feature branch:
+
+1. **GitHub Actions Workflow** automatically triggers on PR events
+2. **SPEC Metadata** (ID, version, status, priority) is extracted from YAML frontmatter
+3. **GitHub Issue** is created with full SPEC content and metadata table
+4. **PR Comment** is added with a link to the created issue
+5. **Labels** are automatically applied based on priority (critical, high, medium, low)
+
+### What Gets Synchronized
+
+**From SPEC to GitHub Issue:**
+- **SPEC ID**: Unique identifier (e.g., AUTH-001, USER-001)
+- **Version**: Semantic versioning (v0.1.0, v1.0.0)
+- **Status**: draft, in-review, in-progress, completed, stable
+- **Priority**: critical, high, medium, low (becomes GitHub label)
+- **Full Content**: EARS requirements, acceptance criteria, dependencies
+
+**GitHub Issue Format:**
+```markdown
+# [SPEC-AUTH-001] User Authentication (v1.0.0)
+
+## SPEC Metadata
+
+| Field | Value |
+|-------|-------|
+| **ID** | AUTH-001 |
+| **Version** | v1.0.0 |
+| **Status** | in-progress |
+| **Priority** | high |
+
+## SPEC Document
+
+[Full SPEC content from .moai/specs/SPEC-AUTH-001/spec.md]
+
+---
+
+📎 **Branch**: `feature/AUTH-001`
+🔗 **PR**: #123
+📝 **Auto-synced**: This issue is automatically synchronized from the SPEC document
+```
+
+### Features
+
+✅ **Automatic Issue Creation**: GitHub Issue created on every PR with SPEC file changes
+✅ **Metadata Extraction**: ID, version, status, priority automatically parsed from YAML frontmatter
+✅ **PR Integration**: Issue linked to PR via automatic comment
+✅ **Label Management**: Priority-based labels (critical, high, medium, low) auto-applied
+✅ **CodeRabbit Review** (local only): AI-powered SPEC quality validation in local development
+
+### Setup Requirements
+
+**GitHub Actions Workflow**: `.github/workflows/spec-issue-sync.yml`
+**GitHub Issue Template**: `.github/ISSUE_TEMPLATE/spec.yml`
+**GitHub Labels**: `spec`, `planning`, `critical`, `high`, `medium`, `low`
+
+All templates are automatically installed with MoAI-ADK and synced during `moai-adk init`.
+
+### CodeRabbit Integration (Local Only)
+
+When working in your **local development environment**, CodeRabbit provides automatic SPEC quality review:
+
+**What CodeRabbit Reviews:**
+- ✅ All 7 required metadata fields (id, version, status, created, updated, author, priority)
+- ✅ HISTORY section formatting and chronological order
+- ✅ EARS requirements structure (Ubiquitous, Event-driven, State-driven, Constraints, Optional)
+- ✅ Acceptance criteria in Given-When-Then format
+- ✅ @TAG system compliance for traceability
+
+**CodeRabbit Configuration**: `.coderabbit.yaml` (local only, not distributed in packages)
+
+> **Note**: CodeRabbit integration is available only in local development environments. Package users receive core GitHub Issue automation without CodeRabbit review.
+
+### Workflow Example
+
+```bash
+# 1. Create SPEC
+/alfred:1-plan "User authentication feature"
+
+# 2. SPEC file created at .moai/specs/SPEC-AUTH-001/spec.md
+# 3. Feature branch created: feature/SPEC-AUTH-001
+# 4. Draft PR created (team mode)
+
+# 5. GitHub Actions automatically:
+#    - Parses SPEC metadata
+#    - Creates GitHub Issue #45
+#    - Adds PR comment: "✅ SPEC GitHub Issue Created - Issue: #45"
+#    - Applies labels: spec, planning, high
+
+# 6. CodeRabbit reviews SPEC (local only):
+#    - Validates metadata
+#    - Checks EARS requirements
+#    - Provides quality score
+
+# 7. Continue with TDD implementation
+/alfred:2-run AUTH-001
+```
+
+### Benefits
+
+1. **Centralized Tracking**: All SPEC requirements tracked as GitHub Issues
+2. **Team Visibility**: Non-technical stakeholders can follow progress via Issues
+3. **Automated Workflow**: No manual issue creation—fully automated from SPEC to Issue
+4. **Traceability**: Direct link between SPEC files, Issues, PRs, and implementation
+5. **Quality Assurance**: CodeRabbit validates SPEC quality before implementation (local only)
+
+---
+
 ## 5 Key Concepts
 
 MoAI-ADK consists of 5 key concepts. Each concept connects to the others, and together they create a powerful development system.
@@ -1467,6 +1579,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Version     | Key Features                                                                                     | Date       |
 | ----------- | ------------------------------------------------------------------------------------------------ | ---------- |
+| **v0.5.7**  | 🎯 SPEC → GitHub Issue automation + CodeRabbit integration + Auto PR comments                    | 2025-10-27 |
 | **v0.4.11** | ✨ TAG Guard system + CLAUDE.md formatting improvements + Code cleanup                           | 2025-10-23 |
 | **v0.4.10** | 🔧 Hook robustness improvements + Bilingual documentation + Template language config             | 2025-10-23 |
 | **v0.4.9**  | 🎯 Hook JSON schema validation fixes + Comprehensive tests (468/468 passing)                     | 2025-10-23 |

{moai_adk-0.5.6 → moai_adk-0.6.0}/README.md

@@ -29,7 +29,6 @@ If you've **already installed it and want to understand the concepts**, we recom
 | What do Plan/Run/Sync commands do? | [Command Cheat Sheet](#command-cheat-sheet)                              |
 | What are SPEC, TDD, TAG?           | [5 Key Concepts](#5-key-concepts)                                        |
 | Tell me about agents/Skills        | [Sub-agents & Skills Overview](#sub-agents--skills-overview)             |
-| I want a 4-week hands-on project   | [Second Practice: Mini Kanban Board](#second-practice-mini-kanban-board) |
 | Want to dive deeper?               | [Additional Resources](#additional-resources)                            |
 
 ---
@@ -590,6 +589,119 @@ graph TD
 
 ---
 
+## SPEC GitHub Issue Automation
+
+MoAI-ADK now provides **automatic GitHub Issue synchronization** from SPEC documents, seamlessly integrating requirements with issue tracking in team mode.
+
+### How It Works
+
+When you create a SPEC document using `/alfred:1-plan` and push it to a feature branch:
+
+1. **GitHub Actions Workflow** automatically triggers on PR events
+2. **SPEC Metadata** (ID, version, status, priority) is extracted from YAML frontmatter
+3. **GitHub Issue** is created with full SPEC content and metadata table
+4. **PR Comment** is added with a link to the created issue
+5. **Labels** are automatically applied based on priority (critical, high, medium, low)
+
+### What Gets Synchronized
+
+**From SPEC to GitHub Issue:**
+- **SPEC ID**: Unique identifier (e.g., AUTH-001, USER-001)
+- **Version**: Semantic versioning (v0.1.0, v1.0.0)
+- **Status**: draft, in-review, in-progress, completed, stable
+- **Priority**: critical, high, medium, low (becomes GitHub label)
+- **Full Content**: EARS requirements, acceptance criteria, dependencies
+
+**GitHub Issue Format:**
+```markdown
+# [SPEC-AUTH-001] User Authentication (v1.0.0)
+
+## SPEC Metadata
+
+| Field | Value |
+|-------|-------|
+| **ID** | AUTH-001 |
+| **Version** | v1.0.0 |
+| **Status** | in-progress |
+| **Priority** | high |
+
+## SPEC Document
+
+[Full SPEC content from .moai/specs/SPEC-AUTH-001/spec.md]
+
+---
+
+📎 **Branch**: `feature/AUTH-001`
+🔗 **PR**: #123
+📝 **Auto-synced**: This issue is automatically synchronized from the SPEC document
+```
+
+### Features
+
+✅ **Automatic Issue Creation**: GitHub Issue created on every PR with SPEC file changes
+✅ **Metadata Extraction**: ID, version, status, priority automatically parsed from YAML frontmatter
+✅ **PR Integration**: Issue linked to PR via automatic comment
+✅ **Label Management**: Priority-based labels (critical, high, medium, low) auto-applied
+✅ **CodeRabbit Review** (local only): AI-powered SPEC quality validation in local development
+
+### Setup Requirements
+
+**GitHub Actions Workflow**: `.github/workflows/spec-issue-sync.yml`
+**GitHub Issue Template**: `.github/ISSUE_TEMPLATE/spec.yml`
+**GitHub Labels**: `spec`, `planning`, `critical`, `high`, `medium`, `low`
+
+All templates are automatically installed with MoAI-ADK and synced during `moai-adk init`.
+
+### CodeRabbit Integration (Local Only)
+
+When working in your **local development environment**, CodeRabbit provides automatic SPEC quality review:
+
+**What CodeRabbit Reviews:**
+- ✅ All 7 required metadata fields (id, version, status, created, updated, author, priority)
+- ✅ HISTORY section formatting and chronological order
+- ✅ EARS requirements structure (Ubiquitous, Event-driven, State-driven, Constraints, Optional)
+- ✅ Acceptance criteria in Given-When-Then format
+- ✅ @TAG system compliance for traceability
+
+**CodeRabbit Configuration**: `.coderabbit.yaml` (local only, not distributed in packages)
+
+> **Note**: CodeRabbit integration is available only in local development environments. Package users receive core GitHub Issue automation without CodeRabbit review.
+
+### Workflow Example
+
+```bash
+# 1. Create SPEC
+/alfred:1-plan "User authentication feature"
+
+# 2. SPEC file created at .moai/specs/SPEC-AUTH-001/spec.md
+# 3. Feature branch created: feature/SPEC-AUTH-001
+# 4. Draft PR created (team mode)
+
+# 5. GitHub Actions automatically:
+#    - Parses SPEC metadata
+#    - Creates GitHub Issue #45
+#    - Adds PR comment: "✅ SPEC GitHub Issue Created - Issue: #45"
+#    - Applies labels: spec, planning, high
+
+# 6. CodeRabbit reviews SPEC (local only):
+#    - Validates metadata
+#    - Checks EARS requirements
+#    - Provides quality score
+
+# 7. Continue with TDD implementation
+/alfred:2-run AUTH-001
+```
+
+### Benefits
+
+1. **Centralized Tracking**: All SPEC requirements tracked as GitHub Issues
+2. **Team Visibility**: Non-technical stakeholders can follow progress via Issues
+3. **Automated Workflow**: No manual issue creation—fully automated from SPEC to Issue
+4. **Traceability**: Direct link between SPEC files, Issues, PRs, and implementation
+5. **Quality Assurance**: CodeRabbit validates SPEC quality before implementation (local only)
+
+---
+
 ## 5 Key Concepts
 
 MoAI-ADK consists of 5 key concepts. Each concept connects to the others, and together they create a powerful development system.
@@ -1428,6 +1540,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Version     | Key Features                                                                                     | Date       |
 | ----------- | ------------------------------------------------------------------------------------------------ | ---------- |
+| **v0.5.7**  | 🎯 SPEC → GitHub Issue automation + CodeRabbit integration + Auto PR comments                    | 2025-10-27 |
 | **v0.4.11** | ✨ TAG Guard system + CLAUDE.md formatting improvements + Code cleanup                           | 2025-10-23 |
 | **v0.4.10** | 🔧 Hook robustness improvements + Bilingual documentation + Template language config             | 2025-10-23 |
 | **v0.4.9**  | 🎯 Hook JSON schema validation fixes + Comprehensive tests (468/468 passing)                     | 2025-10-23 |

{moai_adk-0.5.6 → moai_adk-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "moai-adk"
-version = "0.5.6"
+version = "0.6.0"
 description = "MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0"
 readme = "README.md"
 requires-python = ">=3.13"

{moai_adk-0.5.6 → moai_adk-0.6.0}/src/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-0.5.6 → moai_adk-0.6.0}/src/moai_adk/core/project/phase_executor.py

@@ -191,7 +191,10 @@ class PhaseExecutor:
         # Ensure project section exists and set defaults
         if "project" not in config:
             config["project"] = {}
-        config["project"]["optimized"] = False  # Default value
+        # Type guard for mypy
+        project_config = config["project"]
+        if isinstance(project_config, dict):
+            project_config["optimized"] = False  # Default value
 
         # Write config.json
         config_path = project_path / ".moai" / "config.json"

{moai_adk-0.5.6 → moai_adk-0.6.0}/src/moai_adk/templates/.claude/commands/alfred/1-plan.md

@@ -5,19 +5,19 @@ description: "Planning (brainstorming, plan writing, design discussion) + Branch
 # - ko: "계획 수립 (브레인스토밍, 설계 논의) + 브랜치/PR 생성"
 # - ja: "計画策定（ブレインストーミング、設計議論）+ ブランチ/PR作成"
 # - zh: "规划（头脑风暴、设计讨论）+ 分支/PR创建"
-argument-hint: "Title 1 Title 2 ... | SPEC-ID modifications"
+argument-hint: Title 1 Title 2 ... | SPEC-ID modifications
 allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - MultiEdit
-  - Grep
-  - Glob
-  - TodoWrite
-  - Bash(git:*)
-  - Bash(gh:*)
-  - Bash(rg:*)
-  - Bash(mkdir:*)
+- Read
+- Write
+- Edit
+- MultiEdit
+- Grep
+- Glob
+- TodoWrite
+- Bash(git:*)
+- Bash(gh:*)
+- Bash(rg:*)
+- Bash(mkdir:*)
 ---
 
 # 🏗️ MoAI-ADK Step 1: Establish a plan (Plan) - Always make a plan first and then proceed.
@@ -29,7 +29,7 @@ allowed-tools:
 
 **Plan for**: $ARGUMENTS
 
-## 💡 Planning philosophy: “Always make a plan first and then proceed.”
+## 💡 Planning philosophy: "Always make a plan first and then proceed."
 
 `/alfred:1-plan` is a general-purpose command that **creates a plan**, rather than simply “creating” a SPEC document.
 

moai_adk-0.6.0/src/moai_adk/templates/.github/ISSUE_TEMPLATE/spec.yml

@@ -0,0 +1,176 @@
+name: 📋 SPEC Document
+description: Create a new SPEC document for feature planning
+title: "[SPEC-] "
+labels: ["spec", "planning"]
+assignees: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## 📋 SPEC Metadata
+
+        Fill out the SPEC details below. This will be synchronized with the SPEC document and GitHub Issue.
+
+  - type: input
+    id: spec-id
+    attributes:
+      label: SPEC ID
+      description: "Format: DOMAIN-###. Example: AUTH-001, API-DESIGN-001"
+      placeholder: "AUTH-001"
+    validations:
+      required: true
+
+  - type: input
+    id: spec-title
+    attributes:
+      label: SPEC Title
+      description: "Brief description of the specification"
+      placeholder: "JWT-based authentication system"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      description: "Feature priority level"
+      options:
+        - "critical"
+        - "high"
+        - "medium"
+        - "low"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      description: "SPEC category"
+      options:
+        - "API"
+        - "Backend"
+        - "Frontend"
+        - "Infrastructure"
+        - "Security"
+        - "Testing"
+        - "DevOps"
+        - "Documentation"
+        - "Performance"
+        - "Other"
+    validations:
+      required: true
+
+  - type: textarea
+    id: ubiquitous-requirements
+    attributes:
+      label: "Ubiquitous Requirements"
+      description: "Statements that apply universally to the system"
+      placeholder: |
+        - The system must provide JWT-based authentication
+        - The system must support token expiration
+      value: "### Ubiquitous\n"
+    validations:
+      required: true
+
+  - type: textarea
+    id: event-requirements
+    attributes:
+      label: "Event-driven Requirements (WHEN)"
+      description: "Event-triggered requirements in EARS format"
+      placeholder: |
+        - WHEN the user submits login credentials, the system must validate them against the database
+        - WHEN credentials are valid, the system must issue a JWT token with expiration
+      value: "### Event-driven (WHEN)\n"
+    validations:
+      required: false
+
+  - type: textarea
+    id: state-requirements
+    attributes:
+      label: "State-driven Requirements (WHILE)"
+      description: "State-based requirements in EARS format"
+      placeholder: |
+        - WHILE the token is unexpired, the system must allow access to protected resources
+        - WHILE the user is logged in, the system must track the session
+      value: "### State-driven (WHILE)\n"
+    validations:
+      required: false
+
+  - type: textarea
+    id: optional-requirements
+    attributes:
+      label: "Optional Requirements (WHERE)"
+      description: "Optional features and capabilities"
+      placeholder: |
+        - WHERE the user requests token refresh, the system can issue a new token
+        - WHERE OAuth2 is available, the system can support social login
+      value: "### Optional (WHERE)\n"
+    validations:
+      required: false
+
+  - type: textarea
+    id: constraints
+    attributes:
+      label: "Constraints (IF)"
+      description: "System constraints and conditions"
+      placeholder: |
+        - IF the token has expired, the system must return 401 Unauthorized
+        - IF the password is incorrect, the system must reject the login attempt
+      value: "### Constraints (IF)\n"
+    validations:
+      required: false
+
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: "Acceptance Criteria (Given-When-Then)"
+      description: "At least 2-3 test scenarios"
+      placeholder: |
+        **Scenario 1: Successful Login**
+        - Given a user with valid credentials exists
+        - When the user submits their credentials
+        - Then the system returns a valid JWT token
+
+        **Scenario 2: Token Expiration**
+        - Given a user with an expired token
+        - When the user tries to access a protected resource
+        - Then the system returns a 401 Unauthorized response
+      value: "## Acceptance Criteria\n\n"
+    validations:
+      required: true
+
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: "Dependencies"
+      description: "Related SPECs, tasks, or blockers"
+      placeholder: |
+        - Related: SPEC-SECURITY-001
+        - Blocks: SPEC-API-DESIGN-001
+        - Depends on: SPEC-DATABASE-001
+    validations:
+      required: false
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: "Additional Notes"
+      description: "Technical notes, assumptions, or context"
+      placeholder: |
+        - Consider token refresh token rotation
+        - JWT payload should be minimal for performance
+        - Consider rate limiting on login attempts
+    validations:
+      required: false
+
+  - type: markdown
+    attributes:
+      value: |
+        ## 📚 Reference
+
+        - **SPEC Metadata Guide**: See `.moai/memory/spec-metadata.md`
+        - **EARS Syntax Guide**: See `.moai/memory/development-guide.md`
+        - **Acceptance Criteria**: Use Given-When-Then (Gherkin) format
+        - **@TAG System**: @SPEC, @TEST, @CODE, @DOC traceability