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

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

@@ -1,137 +0,0 @@
-# moai-spec-authoring Skill
-
-**Version**: 1.2.0
-**Created**: 2025-10-23
-**Updated**: 2025-10-29
-**Status**: Active
-**Tier**: Foundation
-
-## Overview
-
-Comprehensive guide for authoring SPEC documents in MoAI-ADK projects. Provides complete YAML metadata structure, EARS syntax patterns, version management strategies, and validation tools.
-
-## Key Features
-
-- **7 Required + 9 Optional Metadata Fields**: Complete reference with lifecycle examples
-- **5 Official EARS Patterns**: Ubiquitous, Event-driven, State-driven, Optional, Unwanted Behaviors
-- **Version Lifecycle**: Semantic versioning from draft to production
-- **TAG Integration**: @SPEC, @TEST, @CODE, @DOC chain management
-- **Validation Tools**: Pre-submission checklist and automation scripts
-- **Common Pitfalls**: Prevention strategies for 7 major issues
-
-## File Structure (Progressive Disclosure)
-
-```
-.claude/skills/moai-spec-authoring/
-├── SKILL.md          # Core overview + Quick Start (~500 words)
-├── reference.md      # Complete metadata reference + EARS syntax
-├── examples.md       # Real-world examples + patterns + troubleshooting
-├── examples/
-│   └── validate-spec.sh  # Automated SPEC validation script
-└── README.md         # This file
-```
-
-## Quick Links
-
-- **Quick Start**: [SKILL.md](./SKILL.md#quick-start-5-step-spec-creation)
-- **Metadata Reference**: [reference.md](./reference.md#complete-metadata-field-reference)
-- **EARS Syntax**: [reference.md](./reference.md#ears-requirement-syntax)
-- **Examples**: [examples.md](./examples.md#real-world-ears-examples)
-- **Troubleshooting**: [examples.md](./examples.md#troubleshooting)
-
-## Usage
-
-### Automatic Activation
-
-This Skill automatically loads when:
-- `/alfred:1-plan` command is executed
-- SPEC document creation is requested
-- Requirements clarification is discussed
-
-### Manual Reference
-
-Consult detailed sections for:
-- SPEC authoring best practices
-- Existing SPEC document validation
-- Metadata issue troubleshooting
-- EARS syntax pattern reference
-
-## Validation Command
-
-```bash
-# Validate SPEC metadata
-rg "^(id|version|status|created|updated|author|priority):" .moai/specs/SPEC-AUTH-001/spec.md
-
-# Check for duplicate IDs
-rg "@SPEC:AUTH-001" -n .moai/specs/
-
-# Scan entire TAG chain
-rg '@(SPEC|TEST|CODE|DOC):AUTH-001' -n
-
-# Use automated script
-./examples/validate-spec.sh .moai/specs/SPEC-AUTH-001
-```
-
-## Example SPEC Structure
-
-```markdown
----
-id: AUTH-001
-version: 0.0.1
-status: draft
-created: 2025-10-29
-updated: 2025-10-29
-author: @YourHandle
-priority: high
----
-
-# @SPEC:AUTH-001: JWT Authentication System
-
-## HISTORY
-### v0.0.1 (2025-10-29)
-- **INITIAL**: JWT authentication SPEC draft
-
-## Environment
-**Runtime**: Node.js 20.x
-
-## Assumptions
-1. User storage: PostgreSQL
-2. Secret management: Environment variables
-
-## 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.
-
-### 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.
-
-### Unwanted Behaviors
-**UB-001**: IF a token has expired, THEN the system shall deny access and return HTTP 401.
-```
-
-## Integration
-
-Works seamlessly with:
-- `spec-builder` agent - SPEC creation
-- `moai-foundation-ears` - EARS syntax patterns
-- `moai-foundation-specs` - Metadata validation
-- `moai-foundation-tags` - TAG system integration
-
-## Support
-
-For questions or issues:
-1. Refer to comprehensive documentation: `SKILL.md`, `reference.md`, `examples.md`
-2. Use `/alfred:1-plan` for guided SPEC creation
-3. Review existing SPECs in `.moai/specs/` for examples
-
----
-
-**Maintained By**: MoAI-ADK Team
-**Last Updated**: 2025-10-29

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

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

@@ -1,161 +0,0 @@
-#!/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 "=========================================="