moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

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

@@ -0,0 +1,219 @@
+---
+name: moai-alfred-spec-authoring
+version: 1.2.0
+created: 2025-10-23
+updated: 2025-11-02
+status: active
+description: SPEC document authoring guide - YAML metadata, EARS syntax (5 patterns with Unwanted Behaviors), validation checklist
+keywords: ['spec', 'authoring', 'ears', 'metadata', 'requirements', 'tdd', 'planning']
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+---
+
+# SPEC Authoring Skill
+
+## Skill Metadata
+
+| Field | Value |
+| ----- | ----- |
+| **Skill Name** | moai-alfred-spec-authoring |
+| **Version** | 1.2.0 (2025-11-02) |
+| **Allowed tools** | Read, Bash, Glob |
+| **Auto-load** | `/alfred:1-plan`, SPEC authoring tasks |
+| **Tier** | Alfred |
+
+---
+
+## What It Does
+
+Comprehensive guide for authoring SPEC documents in MoAI-ADK. Provides YAML metadata structure (7 required + 9 optional fields), official EARS requirement syntax (5 patterns including Unwanted Behaviors), version management lifecycle, TAG integration, and validation strategies.
+
+**Key capabilities**:
+- Step-by-step SPEC creation workflow
+- Complete metadata field reference with lifecycle rules
+- EARS syntax templates and real-world patterns
+- Pre-submission validation checklist
+- Common pitfalls prevention guide
+- `/alfred:1-plan` workflow integration
+
+---
+
+## When to Use
+
+**Automatic triggers**:
+- `/alfred:1-plan` command execution
+- SPEC document creation requests
+- Requirements clarification discussions
+- Feature planning sessions
+
+**Manual invocation**:
+- Learn SPEC authoring best practices
+- Validate existing SPEC documents
+- Troubleshoot metadata issues
+- Understand EARS syntax patterns
+
+---
+
+## Quick Start: 5-Step SPEC Creation
+
+### Step 1: Initialize SPEC Directory
+
+```bash
+mkdir -p .moai/specs/SPEC-{DOMAIN}-{NUMBER}
+# Example: Authentication feature
+mkdir -p .moai/specs/SPEC-AUTH-001
+```
+
+### Step 2: Write YAML Front Matter
+
+```yaml
+---
+id: AUTH-001
+version: 0.0.1
+status: draft
+created: 2025-10-29
+updated: 2025-10-29
+author: @YourGitHubHandle
+priority: high
+---
+```
+
+### Step 3: Add SPEC Title & HISTORY
+
+```markdown
+# @SPEC:AUTH-001: JWT Authentication System
+
+## HISTORY
+
+### v0.0.1 (2025-10-29)
+- **INITIAL**: JWT authentication SPEC draft created
+- **AUTHOR**: @YourHandle
+```
+
+### Step 4: Define Environment & Assumptions
+
+```markdown
+## Environment
+
+**Runtime**: Node.js 20.x or later
+**Framework**: Express.js
+**Database**: PostgreSQL 15+
+
+## Assumptions
+
+1. User credentials stored in PostgreSQL
+2. JWT secrets managed via environment variables
+3. Server clock synchronized with NTP
+```
+
+### Step 5: Write EARS Requirements
+
+```markdown
+## Requirements
+
+### Ubiquitous Requirements
+**UR-001**: The system shall provide JWT-based authentication.
+
+### Event-driven Requirements
+**ER-001**: WHEN the user submits valid credentials, the system shall issue a JWT token with 15-minute expiration.
+
+### State-driven Requirements
+**SR-001**: WHILE the user is in an authenticated state, the system shall permit access to protected resources.
+
+### Optional Features
+**OF-001**: WHERE multi-factor authentication is enabled, the system can require OTP verification after password confirmation.
+
+### Unwanted Behaviors
+**UB-001**: IF a token has expired, THEN the system shall deny access and return HTTP 401.
+```
+
+---
+
+## Five EARS Pattern Overview
+
+| Pattern | Keyword | Purpose | Example |
+|---------|---------|---------|---------|
+| **Ubiquitous** | shall | Core functionality always active | "The system shall provide login capability" |
+| **Event-driven** | WHEN | Response to specific events | "WHEN login fails, display error" |
+| **State-driven** | WHILE | Persistent behavior during state | "WHILE in authenticated state, permit access" |
+| **Optional** | WHERE | Conditional features based on flags | "WHERE premium enabled, unlock feature" |
+| **Unwanted Behaviors** | IF-THEN | Error handling, quality gates, business rules | "IF token expires, deny access + return 401" |
+
+---
+
+## Seven Required Metadata Fields
+
+1. **id**: `<DOMAIN>-<NUMBER>` (e.g., `AUTH-001`) - Immutable identifier
+2. **version**: `MAJOR.MINOR.PATCH` (e.g., `0.0.1`) - Semantic versioning
+3. **status**: `draft` | `active` | `completed` | `deprecated`
+4. **created**: `YYYY-MM-DD` - Initial creation date
+5. **updated**: `YYYY-MM-DD` - Final modification date
+6. **author**: `@GitHubHandle` - Primary author (@ prefix required)
+7. **priority**: `critical` | `high` | `medium` | `low`
+
+**Version Lifecycle**:
+- `0.0.x` → draft (authoring phase)
+- `0.1.0` → completed (implementation done)
+- `1.0.0` → stable (production-ready)
+
+---
+
+## Validation Checklist
+
+### Metadata Validation
+- [ ] All 7 required fields present
+- [ ] `author` field includes @ prefix
+- [ ] `version` format is `0.x.y`
+- [ ] `id` is not duplicated (`rg "@SPEC:AUTH-001" -n .moai/specs/`)
+
+### Content Validation
+- [ ] YAML Front Matter complete
+- [ ] Title includes `@SPEC:{ID}` TAG block
+- [ ] HISTORY section has v0.0.1 INITIAL entry
+- [ ] Environment section defined
+- [ ] Assumptions section defined (minimum 3 items)
+- [ ] Requirements section uses EARS patterns
+- [ ] Traceability section shows TAG chain structure
+
+### EARS Syntax Validation
+- [ ] Ubiquitous: "shall" + capability
+- [ ] Event-driven: Starts with "WHEN [trigger]"
+- [ ] State-driven: Starts with "WHILE [state]"
+- [ ] Optional: Starts with "WHERE [feature]", uses "can"
+- [ ] Unwanted Behaviors: "IF-THEN" or direct constraint expression
+
+---
+
+## Common Pitfalls
+
+1. ❌ **Changing SPEC ID after assignment** → Breaks TAG chain
+2. ❌ **Skipping HISTORY updates** → Content changes without audit trail
+3. ❌ **Jumping version numbers** → v0.0.1 → v1.0.0 without intermediate steps
+4. ❌ **Ambiguous requirements** → "Fast and user-friendly" (unmeasurable)
+5. ❌ **Missing @ prefix in author** → `author: Goos` instead of `author: @Goos`
+6. ❌ **Mixing EARS patterns** → Multiple keywords in single requirement
+
+---
+
+## Related Skills
+
+- `moai-foundation-ears` - Official EARS syntax patterns
+- `moai-foundation-specs` - Metadata validation automation
+- `moai-foundation-tags` - TAG system integration
+- `moai-alfred-spec-metadata-validation` - Automated validation
+
+---
+
+## Detailed Reference
+
+- **Full Metadata Reference**: [reference.md](./reference.md)
+- **Practical Examples**: [examples.md](./examples.md)
+
+---
+
+**Last Updated**: 2025-10-29
+**Version**: 1.2.0
+**Maintained By**: MoAI-ADK Team
+**Support**: Use `/alfred:1-plan` command for guided SPEC creation

moai_adk/templates/.claude/skills/moai-alfred-spec-authoring/examples/validate-spec.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# validate-spec.sh - SPEC validation helper for MoAI-ADK
+# Usage: ./validate-spec.sh .moai/specs/SPEC-AUTH-001
+
+set -e
+
+SPEC_DIR="$1"
+
+if [ -z "$SPEC_DIR" ]; then
+  echo "Usage: $0 <SPEC_DIR>"
+  echo "Example: $0 .moai/specs/SPEC-AUTH-001"
+  exit 1
+fi
+
+if [ ! -d "$SPEC_DIR" ]; then
+  echo "Error: Directory $SPEC_DIR does not exist"
+  exit 1
+fi
+
+if [ ! -f "$SPEC_DIR/spec.md" ]; then
+  echo "Error: spec.md not found in $SPEC_DIR"
+  exit 1
+fi
+
+echo "=========================================="
+echo "Validating SPEC: $SPEC_DIR"
+echo "=========================================="
+echo ""
+
+# Check required fields
+echo -n "Required fields (7)... "
+REQUIRED_COUNT=$(rg "^(id|version|status|created|updated|author|priority):" "$SPEC_DIR/spec.md" | wc -l | tr -d ' ')
+if [ "$REQUIRED_COUNT" -eq 7 ]; then
+  echo "✅ ($REQUIRED_COUNT/7)"
+else
+  echo "❌ ($REQUIRED_COUNT/7)"
+  echo "  Missing fields. Expected: id, version, status, created, updated, author, priority"
+fi
+
+# Check author format
+echo -n "Author format (@Handle)... "
+if rg "^author: @[A-Z]" "$SPEC_DIR/spec.md" > /dev/null 2>&1; then
+  echo "✅"
+else
+  echo "❌"
+  echo "  Expected format: author: @YourHandle"
+fi
+
+# Check version format
+echo -n "Version format (0.x.y)... "
+if rg "^version: 0\.\d+\.\d+" "$SPEC_DIR/spec.md" > /dev/null 2>&1; then
+  echo "✅"
+else
+  echo "❌"
+  echo "  Expected format: version: 0.x.y (e.g., 0.0.1, 0.1.0)"
+fi
+
+# Check HISTORY section
+echo -n "HISTORY section... "
+if rg "^## HISTORY" "$SPEC_DIR/spec.md" > /dev/null 2>&1; then
+  echo "✅"
+else
+  echo "❌"
+  echo "  Missing HISTORY section"
+fi
+
+# Check TAG block
+echo -n "TAG block (@SPEC:ID)... "
+if rg "^# @SPEC:" "$SPEC_DIR/spec.md" > /dev/null 2>&1; then
+  echo "✅"
+else
+  echo "❌"
+  echo "  Expected format: # @SPEC:YOUR-ID: Title"
+fi
+
+# Check Environment section
+echo -n "Environment section... "
+if rg "^## Environment" "$SPEC_DIR/spec.md" > /dev/null 2>&1; then
+  echo "✅"
+else
+  echo "⚠️  (optional but recommended)"
+fi
+
+# Check Assumptions section
+echo -n "Assumptions section... "
+if rg "^## Assumptions" "$SPEC_DIR/spec.md" > /dev/null 2>&1; then
+  echo "✅"
+else
+  echo "⚠️  (optional but recommended)"
+fi
+
+# Check Requirements section
+echo -n "Requirements section... "
+if rg "^## Requirements" "$SPEC_DIR/spec.md" > /dev/null 2>&1; then
+  echo "✅"
+else
+  echo "❌"
+  echo "  Missing Requirements section"
+fi
+
+# Check duplicate IDs
+SPEC_ID=$(basename "$SPEC_DIR" | sed 's/SPEC-//')
+echo -n "Duplicate ID check ($SPEC_ID)... "
+DUPLICATE_COUNT=$(rg "@SPEC:$SPEC_ID" -n .moai/specs/ 2>/dev/null | wc -l | tr -d ' ')
+if [ "$DUPLICATE_COUNT" -eq 1 ]; then
+  echo "✅ (1 occurrence)"
+else
+  echo "❌ (found $DUPLICATE_COUNT occurrences)"
+  if [ "$DUPLICATE_COUNT" -gt 1 ]; then
+    echo "  Duplicate SPEC IDs detected:"
+    rg "@SPEC:$SPEC_ID" -n .moai/specs/
+  fi
+fi
+
+# Check EARS patterns
+echo ""
+echo "EARS Pattern Usage:"
+echo -n "  Ubiquitous (UR-XXX)... "
+if rg "^\*\*UR-\d+" "$SPEC_DIR/spec.md" > /dev/null 2>&1; then
+  COUNT=$(rg "^\*\*UR-\d+" "$SPEC_DIR/spec.md" | wc -l | tr -d ' ')
+  echo "✅ ($COUNT found)"
+else
+  echo "⚠️  (none found)"
+fi
+
+echo -n "  Event-driven (ER-XXX)... "
+if rg "^\*\*ER-\d+" "$SPEC_DIR/spec.md" > /dev/null 2>&1; then
+  COUNT=$(rg "^\*\*ER-\d+" "$SPEC_DIR/spec.md" | wc -l | tr -d ' ')
+  echo "✅ ($COUNT found)"
+else
+  echo "⚠️  (none found)"
+fi
+
+echo -n "  State-driven (SR-XXX)... "
+if rg "^\*\*SR-\d+" "$SPEC_DIR/spec.md" > /dev/null 2>&1; then
+  COUNT=$(rg "^\*\*SR-\d+" "$SPEC_DIR/spec.md" | wc -l | tr -d ' ')
+  echo "✅ ($COUNT found)"
+else
+  echo "⚠️  (none found)"
+fi
+
+echo -n "  Optional Features (OF-XXX)... "
+if rg "^\*\*OF-\d+" "$SPEC_DIR/spec.md" > /dev/null 2>&1; then
+  COUNT=$(rg "^\*\*OF-\d+" "$SPEC_DIR/spec.md" | wc -l | tr -d ' ')
+  echo "✅ ($COUNT found)"
+else
+  echo "⚠️  (none found)"
+fi
+
+echo -n "  Unwanted Behaviors (UB-XXX)... "
+if rg "^\*\*UB-\d+" "$SPEC_DIR/spec.md" > /dev/null 2>&1; then
+  COUNT=$(rg "^\*\*UB-\d+" "$SPEC_DIR/spec.md" | wc -l | tr -d ' ')
+  echo "✅ ($COUNT found)"
+else
+  echo "⚠️  (none found)"
+fi
+
+echo ""
+echo "=========================================="
+echo "Validation complete!"
+echo "=========================================="