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

moai_adk/templates/.claude/skills/moai-alfred-spec-metadata-extended/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: "Writing SPEC Documents with Metadata"
+description: "Standards for SPEC authoring including YAML metadata, EARS syntax, HISTORY section, and validation. Guides spec-builder agent through SPEC creation in .moai/specs/SPEC-{ID}/ directory. Covers 7 required metadata fields, 5 EARS patterns, version tracking, changelog format, and @SPEC:ID TAG placement. Essential for /alfred:1-plan command and duplicate detection."
+allowed-tools: "Read, Write, Bash(rg:*), Bash(mkdir:*)"
+---
+
+# SPEC Metadata Standard Skill
+
+## SPEC Directory Structure
+
+```
+.moai/specs/SPEC-{DOMAIN}-{NUMBER}/
+├── spec.md          # Requirements (EARS format) + metadata
+├── plan.md          # Implementation plan
+└── acceptance.md    # Test scenarios, acceptance criteria
+```
+
+## YAML Metadata (7 Fields)
+
+Every SPEC starts with frontmatter:
+
+```yaml
+---
+id: AUTH-001
+title: "User Authentication System"
+version: 0.1.0
+status: active
+created: 2025-11-03
+updated: 2025-11-03
+author: @GOOS🪿엉아
+priority: high
+---
+```
+
+### Field Definitions
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `id` | string | ✅ | Domain-NUMBER (e.g., AUTH-001) |
+| `title` | string | ✅ | User-facing description |
+| `version` | semver | ✅ | Current status (0.x.x = draft) |
+| `status` | enum | ✅ | active\|draft\|deprecated\|archived |
+| `created` | ISO8601 | ✅ | YYYY-MM-DD |
+| `updated` | ISO8601 | ✅ | Last modification date |
+| `author` | string | ✅ | Creator identifier |
+| `priority` | enum | ✅ | critical\|high\|medium\|low |
+
+## EARS Requirements (5 Patterns)
+
+### 1. Ubiquitous (Baseline)
+```
+The system shall provide [capability].
+The system shall validate [input] before [action].
+```
+
+### 2. Event-driven
+```
+WHEN [condition], the system shall [behavior].
+WHEN a user logs in, the system shall verify credentials.
+```
+
+### 3. State-driven
+```
+WHILE [state], the system shall [behavior].
+WHILE authenticated, the system shall allow access.
+```
+
+### 4. Optional Features
+```
+WHERE [condition], the system may [behavior].
+WHERE API key present, the system may enable caching.
+```
+
+### 5. Constraints
+```
+IF [condition], the system shall [constraint].
+IF password invalid, the system shall deny access.
+```
+
+## HISTORY Section
+
+Track all changes:
+
+```markdown
+## HISTORY
+
+### v0.2.0 (2025-11-03)
+- Added email verification requirement
+- Updated password complexity rules
+
+### v0.1.0 (2025-11-01)
+- Initial draft of AUTH-001
+```
+
+## Validation Checklist
+
+- [ ] ID: Domain-NUMBER format (e.g., AUTH-001)
+- [ ] No duplicate @SPEC:ID (`rg "@SPEC:{ID}" .moai/specs/`)
+- [ ] All 7 metadata fields present
+- [ ] version follows semver (0.x.x for draft)
+- [ ] 5+ EARS requirements with different patterns
+- [ ] HISTORY section with at least v0.1.0
+- [ ] Directory: `.moai/specs/SPEC-{ID}/`
+- [ ] @SPEC:ID placed in first 50 lines of spec.md
+
+## Common Patterns
+
+| Scenario | Action |
+|----------|--------|
+| Start new SPEC | Create .moai/specs/SPEC-{DOMAIN}-{NUMBER}/ |
+| Check duplicate | rg "@SPEC:{ID}" .moai/specs/ (should be 0) |
+| Write requirement | Use one of 5 EARS patterns |
+| Update version | Change version field, update HISTORY |
+| Mark deprecated | Set status: deprecated, add note |
+| Link to @CODE | In code comment: @CODE:SPEC-AUTH-001 |

moai_adk/templates/.claude/skills/moai-alfred-spec-metadata-extended/examples.md

@@ -0,0 +1,4 @@
+# Examples
+
+See `reference.md` for practical examples and usage patterns.
+

moai_adk/templates/.claude/skills/moai-alfred-spec-metadata-extended/reference.md

@@ -0,0 +1,348 @@
+# SPEC Metadata Extended - Reference
+
+## YAML Frontmatter Fields
+
+### Field: `id`
+
+**Type**: `string`
+**Required**: ✅ Yes
+**Format**: `{DOMAIN}-{NUMBER}` (e.g., `AUTH-001`, `CACHE-FIX-002`)
+**Rules**:
+- Domain: 2-8 characters, UPPERCASE
+- Number: 3 digits, zero-padded (001, 002, 100)
+- No duplicates allowed across project
+
+**Validation**:
+```bash
+# Check for duplicates
+rg "@SPEC:AUTH-001" .moai/specs/  # Should return exactly 1 hit
+
+# Check format
+rg "^id: [A-Z]+-\d{3}$" .moai/specs/SPEC-*/spec.md
+```
+
+### Field: `title`
+
+**Type**: `string`
+**Required**: ✅ Yes
+**Max Length**: 128 characters
+**Style**: User-facing, descriptive noun phrase
+
+**Examples**:
+- ✅ "User Authentication System"
+- ✅ "Redis Cache Optimization"
+- ❌ "Implement auth" (too vague)
+- ❌ "User Authentication System for Multi-tenant Applications with Role-Based Access Control" (too long)
+
+### Field: `version`
+
+**Type**: `semver` (X.Y.Z)
+**Required**: ✅ Yes
+**Format**: `major.minor.patch`
+**Rules**:
+- Draft: `0.x.x` (no implementation yet)
+- Alpha: `1.0.0-alpha` (partial implementation)
+- Beta: `1.0.0-beta` (mostly done, testing)
+- Release: `1.0.0+` (fully implemented)
+
+**Examples**:
+```yaml
+version: 0.1.0  # Initial draft
+version: 0.2.0  # Requirements refined
+version: 1.0.0  # First implementation
+version: 1.1.0  # Bug fixes + features
+version: 2.0.0  # Major refactor
+```
+
+### Field: `status`
+
+**Type**: `enum`
+**Required**: ✅ Yes
+**Allowed Values**:
+- `draft` – Not ready for implementation
+- `active` – Current work item
+- `in-progress` – Being implemented
+- `completed` – Implemented + tested
+- `deprecated` – No longer used
+- `archived` – Historical reference
+
+**State Transitions**:
+```
+draft → active → in-progress → completed
+                             ↓
+                         deprecated
+                             ↓
+                          archived
+```
+
+### Field: `created`
+
+**Type**: `ISO8601` (YYYY-MM-DD)
+**Required**: ✅ Yes
+**Example**: `2025-11-03`
+**Rule**: Never change after creation
+
+### Field: `updated`
+
+**Type**: `ISO8601` (YYYY-MM-DD)
+**Required**: ✅ Yes
+**Example**: `2025-11-03`
+**Rule**: Update whenever spec changes
+
+### Field: `author`
+
+**Type**: `string`
+**Required**: ✅ Yes
+**Format**: `@USERNAME` or `@NICKNAME`
+**Examples**:
+- `@GOOS🪿엉아`
+- `@alice.smith`
+- `@team-backend`
+
+### Field: `priority`
+
+**Type**: `enum`
+**Required**: ✅ Yes
+**Allowed Values**:
+- `critical` – Blocking other work (P0)
+- `high` – Important feature (P1)
+- `medium` – Nice to have (P2)
+- `low` – Backlog (P3)
+
+## HISTORY Section Format
+
+### Structure
+
+```markdown
+## HISTORY
+
+### v1.1.0 (2025-11-05)
+- Fixed race condition in verification
+- Added timeout handling
+- Updated error messages
+
+### v1.0.0 (2025-11-03)
+- Initial implementation complete
+- All tests passing
+- Documentation updated
+
+### v0.2.0 (2025-11-02)
+- Refined email requirements
+- Added rate limiting constraints
+- Extended EARS patterns
+
+### v0.1.0 (2025-11-01)
+- Initial draft with basic auth
+- Ubiquitous requirements defined
+```
+
+### Rules
+
+- Start with most recent version
+- One entry per version change
+- Bullet points, not paragraphs
+- Link to commits if available
+- Update `updated` field when modifying
+
+## EARS Requirements Format
+
+### Pattern 1: Ubiquitous
+
+```markdown
+- The system shall provide [capability].
+- The system shall validate [input] before [action].
+- The system shall [behavior] within [time] of [trigger].
+
+Examples:
+- The system shall provide user authentication via email.
+- The system shall validate email format (RFC 5322) before storage.
+- The system shall send verification email within 10 seconds of signup.
+```
+
+### Pattern 2: Event-driven
+
+```markdown
+- WHEN [condition], the system shall [behavior].
+- Upon [event], the system shall [action] and [action].
+
+Examples:
+- WHEN a user clicks 'Sign Up', the system shall display signup form.
+- Upon verification link click, the system shall activate user account.
+- WHEN 3 failed attempts occur, the system shall lock the account.
+```
+
+### Pattern 3: State-driven
+
+```markdown
+- WHILE [state], the system shall [behavior].
+- WHILE not [condition], the system shall [action].
+
+Examples:
+- WHILE the user is unauthenticated, the system shall deny access.
+- WHILE session is active, the system shall refresh token automatically.
+- WHILE rate limit not exceeded, the system shall process requests.
+```
+
+### Pattern 4: Optional Features
+
+```markdown
+- WHERE [condition], the system may [behavior].
+- If [feature] enabled, the system may [action].
+
+Examples:
+- WHERE 2FA is enabled, the system may require additional verification.
+- If API quota available, the system may allow batch operations.
+- WHERE user preference set, the system may send notifications.
+```
+
+### Pattern 5: Constraints (Unwanted Behaviors)
+
+```markdown
+- IF [condition], the system shall [constraint].
+- The system shall NOT [unwanted behavior].
+
+Examples:
+- IF password invalid 3x, the system shall lock account.
+- The system shall NOT store plaintext passwords.
+- IF token expired, the system shall return 401 error.
+- The system shall NOT process requests exceeding rate limit.
+```
+
+## TAG Placement
+
+### Location
+
+Place `@SPEC:ID` in first 50 lines of spec.md:
+
+```markdown
+# User Authentication SPEC
+
+@SPEC:AUTH-001
+
+## Overview
+...
+```
+
+### Usage in Code
+
+Link implementation to spec:
+
+```python
+# src/auth.py
+# @CODE:AUTH-001
+
+def verify_email(email: str, token: str) -> bool:
+    """Verify email with token. Requirement: AUTH-001"""
+    # Implementation here
+    pass
+```
+
+## Duplicate Detection
+
+### Before Creating SPEC
+
+```bash
+# Check if ID already exists
+rg "@SPEC:AUTH-001" .moai/specs/
+
+# Expected: 0 hits (if new) or 1 hit (if existing)
+# If >1 hit: ERROR – duplicate detected
+```
+
+### Duplicate Resolution
+
+If duplicate found:
+1. Use different number: AUTH-001 → AUTH-002
+2. Or use different domain: AUTH-001 → SECURITY-001
+3. Recheck with `rg "@SPEC:{NEW-ID}" .moai/specs/`
+
+## Validation Checklist
+
+```bash
+#!/bin/bash
+# validate-spec.sh - Verify SPEC completeness
+
+SPEC_DIR=".moai/specs/SPEC-$1"
+
+if [ ! -d "$SPEC_DIR" ]; then
+  echo "❌ Directory not found: $SPEC_DIR"
+  exit 1
+fi
+
+# Check metadata fields
+for field in "id" "title" "version" "status" "created" "updated" "author" "priority"; do
+  if ! grep "^$field:" "$SPEC_DIR/spec.md" > /dev/null; then
+    echo "❌ Missing field: $field"
+  fi
+done
+
+# Check SPEC ID in file
+SPEC_ID=$(grep "^id:" "$SPEC_DIR/spec.md" | cut -d' ' -f2)
+if ! grep "@SPEC:$SPEC_ID" "$SPEC_DIR/spec.md" > /dev/null; then
+  echo "❌ Missing @SPEC:$SPEC_ID tag in spec.md"
+fi
+
+# Check for EARS patterns (at least 3)
+EARS_COUNT=$(grep -E "^- (The system shall|WHEN|WHILE|WHERE|IF)" "$SPEC_DIR/spec.md" | wc -l)
+if [ "$EARS_COUNT" -lt 5 ]; then
+  echo "⚠️  Only $EARS_COUNT EARS requirements (recommend ≥5)"
+fi
+
+# Check HISTORY section
+if ! grep "^## HISTORY" "$SPEC_DIR/spec.md" > /dev/null; then
+  echo "❌ Missing HISTORY section"
+fi
+
+echo "✅ SPEC validation complete"
+```
+
+## File Structure
+
+```
+.moai/specs/SPEC-AUTH-001/
+├── spec.md           # Requirements + metadata
+├── plan.md           # Implementation plan (phase 2)
+└── acceptance.md     # Test scenarios (phase 2)
+```
+
+### spec.md Contents (Phase 1)
+
+```markdown
+---
+id: AUTH-001
+title: "User Authentication System"
+version: 0.1.0
+status: active
+created: 2025-11-03
+updated: 2025-11-03
+author: @USERNAME
+priority: high
+---
+
+# User Authentication SPEC
+
+@SPEC:AUTH-001
+
+## Overview
+[System description]
+
+## Ubiquitous Requirements
+[The system shall...]
+
+## Event-driven Requirements
+[WHEN... the system shall...]
+
+## State-driven Requirements
+[WHILE... the system shall...]
+
+## Optional Features
+[WHERE... the system may...]
+
+## Constraints
+[IF... the system shall...]
+
+## HISTORY
+
+### v0.1.0 (2025-11-03)
+- Initial draft
+```

moai_adk/templates/.claude/skills/moai-alfred-todowrite-pattern/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: moai-alfred-todowrite-pattern
+description: "TodoWrite auto-initialization patterns from Plan agent, task tracking best practices, status management."
+tier: Alfred
+allowed-tools: "Read"
+---
+
+## What It Does
+
+TodoWrite 자동 초기화, task 상태 관리, phase 구분 규칙을 정의합니다.
+
+## When to Use
+
+- ✅ Task tracking 설정
+- ✅ TodoWrite 상태 관리
+
+---
+
+Learn more in `reference.md`.

moai_adk/templates/.claude/skills/moai-alfred-todowrite-pattern/examples.md

@@ -0,0 +1,4 @@
+# Examples
+
+See `reference.md` for practical examples and usage patterns.
+

moai_adk/templates/.claude/skills/moai-alfred-todowrite-pattern/reference.md

@@ -0,0 +1,211 @@
+# TodoWrite Auto-Initialization Pattern
+
+> **Version**: 0.8.0+
+> **Status**: Active
+> **Updated**: 2025-11-02
+
+## Overview
+
+**OLD Pattern** (manual initialization):
+```python
+# User had to manually initialize TodoWrite
+TodoWrite([
+    {"content": "Analyze project", "status": "pending"},
+    {"content": "Create SPEC", "status": "pending"}
+])
+```
+
+**NEW Pattern** (auto-initialization from Plan agent):
+```python
+# Plan agent generates task list
+plan = Task(
+    subagent_type="Plan",
+    prompt="Create structured plan for: {request}"
+)
+
+# Alfred auto-initializes TodoWrite from plan
+TodoWrite(plan.tasks)  # Automatic from Plan agent output
+```
+
+## Integration with Alfred 4-Step Workflow
+
+### Step 1: Intent Understanding
+- **Goal**: Clarify user intent before any action
+- **TodoWrite**: NO initialization
+- **Output**: Clear understanding of requirements
+
+### Step 2: Plan Creation (NEW: AUTO-INIT)
+- **Goal**: Analyze tasks and initialize progress tracking
+- **Action**: Invoke Plan Agent to decompose tasks
+- **NEW**: **AUTO-INITIALIZE TodoWrite from Plan output**
+- **Output**: Structured task breakdown + initialized TodoWrite
+
+### Step 3: Task Execution
+- **Goal**: Execute tasks with transparent progress tracking
+- **Action**: Execute tasks in order, updating TodoWrite status
+- **TodoWrite**: Update: pending → in_progress → completed
+- **Output**: Completed work, all todos marked done
+
+### Step 4: Report & Commit
+- **Goal**: Document work and create git history
+- **Action**: Generate report (if requested) and commit
+- **TodoWrite**: All tasks should be "completed"
+- **Output**: Git history, documentation
+
+## Plan Agent Output Format
+
+Plan agent should return tasks in TodoWrite-compatible format:
+
+```json
+{
+    "tasks": [
+        {
+            "content": "Analyze SPEC requirements",
+            "activeForm": "Analyzing SPEC requirements",
+            "status": "pending"
+        },
+        {
+            "content": "Write test cases",
+            "activeForm": "Writing test cases",
+            "status": "pending"
+        },
+        {
+            "content": "Implement feature",
+            "activeForm": "Implementing feature",
+            "status": "pending"
+        }
+    ]
+}
+```
+
+## Implementation Pattern
+
+### In /alfred:1-plan Command
+
+```python
+# STEP 2: Plan Creation (with AUTO-INIT)
+plan_result = Task(
+    subagent_type="Plan",
+    prompt=f"""Create structured plan for: {user_request}
+
+Return tasks in this format:
+{{
+    "tasks": [
+        {{"content": "[imperative verb] [object]", "activeForm": "[present continuous]"}},
+        ...
+    ]
+}}
+"""
+)
+
+# AUTO-INIT TodoWrite from Plan output
+tasks = [
+    {
+        "content": task["content"],
+        "activeForm": task["activeForm"],
+        "status": "pending"
+    }
+    for task in plan_result.tasks
+]
+
+TodoWrite(tasks)
+
+# STEP 3: Execute tasks
+for task in plan_result.tasks:
+    TodoWrite([{"content": task["content"], "status": "in_progress"}])
+    execute_task(task)
+    TodoWrite([{"content": task["content"], "status": "completed"}])
+```
+
+## Real-World Example
+
+### User Request
+```
+/alfred:1-plan "Create user authentication feature"
+```
+
+### Step 1: Intent Understanding
+- Clarify: Is JWT or OAuth preferred?
+- Ask for scope: Frontend, backend, or both?
+
+### Step 2: Plan Creation
+Plan agent returns:
+```json
+{
+    "tasks": [
+        {"content": "Design authentication architecture", "activeForm": "Designing authentication architecture"},
+        {"content": "Create database schema", "activeForm": "Creating database schema"},
+        {"content": "Write API endpoints", "activeForm": "Writing API endpoints"},
+        {"content": "Build frontend login form", "activeForm": "Building frontend login form"},
+        {"content": "Write integration tests", "activeForm": "Writing integration tests"}
+    ]
+}
+```
+
+Alfred AUTO-INITIALIZES:
+```
+☑ Design authentication architecture [pending]
+☑ Create database schema [pending]
+☑ Write API endpoints [pending]
+☑ Build frontend login form [pending]
+☑ Write integration tests [pending]
+```
+
+### Step 3: Task Execution
+```
+☑ Design authentication architecture [completed]
+☑ Create database schema [completed]
+☑ Write API endpoints [in_progress]
+...
+```
+
+## Benefits
+
+1. **Consistency**: All workflows start with same TodoWrite structure
+2. **Visibility**: Users see full task list upfront
+3. **Progress tracking**: Clear pending → in_progress → completed flow
+4. **Resumability**: Saved TodoWrite state enables resume feature (Feature 6)
+5. **No manual work**: Plan agent output directly initializes todos
+
+## Backward Compatibility
+
+**Existing workflows** that manually call TodoWrite still work:
+```python
+# Old style still works
+TodoWrite([
+    {"content": "Task 1", "status": "pending"},
+    {"content": "Task 2", "status": "pending"}
+])
+```
+
+**Transition strategy**:
+1. New commands use AUTO-INIT pattern (Week 1)
+2. Existing commands continue supporting manual TodoWrite
+3. Deprecation notice added in v0.9.0
+4. Full migration in v1.0.0
+
+## Testing Checklist
+
+- [ ] Plan agent returns well-formed task list
+- [ ] TodoWrite initializes with all tasks as "pending"
+- [ ] Task execution updates status correctly
+- [ ] Resume feature works with auto-initialized todos
+- [ ] Backward compatibility maintained for manual TodoWrite calls
+
+## Migration Guide for Users
+
+**Before (v0.7.0)**:
+- Manual TodoWrite initialization
+- Inconsistent task structures
+- No automatic initialization
+
+**After (v0.8.0+)**:
+- Automatic TodoWrite from Plan agent
+- Consistent structure across all commands
+- Better progress visibility
+- Supports resume feature
+
+**How to upgrade**:
+1. No action required (automatic)
+2. All 3 commands (`/alfred:1-plan`, `/alfred:2-run`, `/alfred:3-sync`) now support auto-init
+3. Manual TodoWrite calls still work (backward compatible)