moai-adk 0.5.6__py3-none-any.whl → 0.6.0__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/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/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/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

moai_adk/templates/.github/workflows/spec-issue-sync.yml

@@ -0,0 +1,167 @@
+name: 📋 SPEC Issue Sync
+
+on:
+  pull_request:
+    paths:
+      - '.moai/specs/SPEC-*/spec.md'
+    types: [opened, synchronize]
+
+permissions:
+  issues: write
+  pull-requests: write
+  contents: read
+
+jobs:
+  sync-spec-to-issue:
+    runs-on: ubuntu-latest
+    name: 🔄 Sync SPEC to GitHub Issue
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Find and parse SPEC file
+        id: spec
+        run: |
+          set -x  # Enable debug mode
+
+          # Debug: Show current directory and files
+          echo "=== Debug: Current directory ==="
+          pwd
+          ls -la
+
+          echo "=== Debug: Looking for .moai/specs ==="
+          ls -la .moai/ 2>&1 || echo ".moai/ directory not found"
+
+          # Find SPEC files in the PR
+          echo "=== Debug: Searching for SPEC files ==="
+          find . -name "spec.md" -type f 2>&1 || echo "find command failed"
+
+          spec_file=$(find .moai/specs -name "spec.md" -type f 2>&1 | head -1)
+          echo "Found spec_file: [$spec_file]"
+
+          if [ -z "$spec_file" ]; then
+            echo "⚠️  No SPEC file found in .moai/specs"
+            echo "Exiting gracefully (this is expected if no SPEC files changed)"
+            exit 0
+          fi
+
+          echo "✅ Found SPEC file: $spec_file"
+          echo "spec_file=$spec_file" >> $GITHUB_OUTPUT
+
+          # Extract YAML metadata using grep
+          spec_id=$(grep "^id:" "$spec_file" | sed 's/^id: *//' | tr -d ' "')
+          spec_version=$(grep "^version:" "$spec_file" | sed 's/^version: *//' | tr -d ' "')
+          spec_status=$(grep "^status:" "$spec_file" | sed 's/^status: *//' | tr -d ' "')
+          spec_priority=$(grep "^priority:" "$spec_file" | sed 's/^priority: *//' | tr -d ' "')
+
+          # Extract title from H1 heading
+          spec_title=$(grep "^# @SPEC:" "$spec_file" | sed 's/^# @SPEC:[^:]*: //')
+
+          echo "✅ Extracted SPEC metadata:"
+          echo "  ID: $spec_id"
+          echo "  Title: $spec_title"
+          echo "  Version: $spec_version"
+          echo "  Status: $spec_status"
+          echo "  Priority: $spec_priority"
+
+          echo "spec_id=$spec_id" >> $GITHUB_OUTPUT
+          echo "spec_version=$spec_version" >> $GITHUB_OUTPUT
+          echo "spec_status=$spec_status" >> $GITHUB_OUTPUT
+          echo "spec_priority=$spec_priority" >> $GITHUB_OUTPUT
+          echo "spec_title=$spec_title" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Issue
+        if: steps.spec.outputs.spec_id
+        id: create-issue
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          spec_id="${{ steps.spec.outputs.spec_id }}"
+          spec_version="${{ steps.spec.outputs.spec_version }}"
+          spec_title="${{ steps.spec.outputs.spec_title }}"
+          spec_status="${{ steps.spec.outputs.spec_status }}"
+          spec_priority="${{ steps.spec.outputs.spec_priority }}"
+          spec_file="${{ steps.spec.outputs.spec_file }}"
+
+          # Read SPEC content (skip YAML frontmatter: 9 lines + 1 blank = 10 lines total)
+          # Start reading from line 11
+          spec_content=$(tail -n +11 "$spec_file")
+
+          # Create issue body using GitHub Actions recommended pattern
+          # Reference: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+          {
+            echo "## SPEC Metadata"
+            echo ""
+            echo "| Field | Value |"
+            echo "|-------|-------|"
+            echo "| **ID** | $spec_id |"
+            echo "| **Version** | $spec_version |"
+            echo "| **Status** | $spec_status |"
+            echo "| **Priority** | $spec_priority |"
+            echo ""
+            echo "## SPEC Document"
+            echo ""
+            echo "$spec_content"
+            echo ""
+            echo "---"
+            echo ""
+            echo "📎 **Branch**: \`feature/$spec_id\`"
+            echo "🔗 **PR**: #${{ github.event.pull_request.number }}"
+            echo "📝 **Auto-synced**: This issue is automatically synchronized from the SPEC document"
+          } > /tmp/issue_body.txt
+
+          echo "📋 Creating GitHub Issue..."
+          echo "  Title: [SPEC-$spec_id] $spec_title (v$spec_version)"
+          echo "  Body file: /tmp/issue_body.txt"
+          wc -l /tmp/issue_body.txt
+
+          # Create issue with labels using body-file
+          issue_output=$(gh issue create \
+            --title "[SPEC-$spec_id] $spec_title (v$spec_version)" \
+            --body-file /tmp/issue_body.txt \
+            --label "spec" \
+            --label "planning" \
+            --label "$spec_priority" 2>&1)
+
+          echo "$issue_output" | tee /tmp/issue_output.txt
+
+          # Extract issue number from output
+          issue_num=$(echo "$issue_output" | grep -oE '/issues/[0-9]+' | grep -oE '[0-9]+' | head -1)
+
+          if [ -z "$issue_num" ]; then
+            echo "⚠️  Could not extract issue number from output"
+            echo "Full output:"
+            cat /tmp/issue_output.txt
+            exit 1
+          fi
+
+          echo "issue_number=$issue_num" >> $GITHUB_OUTPUT
+          echo "✅ Created issue #$issue_num"
+
+      - name: Add PR comment
+        if: steps.create-issue.outputs.issue_number
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          issue_num="${{ steps.create-issue.outputs.issue_number }}"
+          spec_id="${{ steps.spec.outputs.spec_id }}"
+          spec_title="${{ steps.spec.outputs.spec_title }}"
+
+          # Create PR comment body using same pattern
+          {
+            echo "✅ **SPEC GitHub Issue Created**"
+            echo ""
+            echo "This SPEC has been synchronized to GitHub Issue."
+            echo ""
+            echo "📋 **Issue**: [#$issue_num - SPEC-$spec_id: $spec_title](../issues/$issue_num)"
+            echo "🔗 **SPEC File**: \`.moai/specs/SPEC-$spec_id/spec.md\`"
+            echo ""
+            echo "The issue will be automatically updated as you modify the SPEC document."
+          } > /tmp/pr_comment.txt
+
+          gh pr comment ${{ github.event.pull_request.number }} --body-file /tmp/pr_comment.txt
+          echo "✅ Added PR comment linking to issue #$issue_num"