moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-workflow-spec/modules/advanced-patterns.md

@@ -0,0 +1,237 @@
+# Advanced SPEC Patterns
+
+## Custom SPEC Templates
+
+This module provides advanced patterns for SPEC workflow management, including template customization, validation automation, and workflow optimization strategies.
+
+---
+
+## SPEC Template Customization
+
+### Template Inheritance Pattern
+
+Create base templates that can be extended for specific use cases:
+
+Base Template Structure:
+- Header section with standard metadata fields
+- Requirements section with placeholder EARS patterns
+- Constraints section with technical and business categories
+- Success criteria section with functional, performance, and security categories
+- Test scenarios section with category organization
+
+Extension Process:
+- Copy base template to new SPEC file
+- Fill in specific requirements for your feature
+- Add domain-specific constraints
+- Define measurable success criteria
+- Create comprehensive test scenarios
+
+### Domain-Specific Templates
+
+Backend API Template:
+- Includes API specification section
+- Response schema definitions
+- Rate limiting and authentication requirements
+- Performance targets for endpoint response times
+- Database schema considerations
+
+Frontend Component Template:
+- Includes component API section
+- Props interface definition
+- Accessibility requirements (WCAG compliance)
+- Styling constraints and design tokens
+- Storybook documentation requirements
+
+Workflow Template:
+- Includes preconditions and side effects sections
+- State machine definitions
+- Rollback strategy documentation
+- Compensating transaction patterns
+- Multi-step orchestration requirements
+
+---
+
+## Validation Automation
+
+### Automated Quality Checks
+
+EARS Pattern Validation:
+- Verify each requirement uses exactly one EARS pattern
+- Check for pattern-appropriate keywords (WHEN/THEN, IF/THEN, etc.)
+- Detect mixed patterns within single requirements
+- Flag ambiguous language that needs clarification
+
+Test Coverage Validation:
+- Map each requirement to corresponding test scenarios
+- Identify requirements without test coverage
+- Detect orphan test scenarios without linked requirements
+- Calculate coverage percentage for SPEC completeness
+
+Success Criteria Validation:
+- Verify all criteria are quantifiable (contain numeric targets)
+- Check for measurable metrics (response time, coverage percentage, etc.)
+- Flag qualitative criteria that cannot be objectively verified
+- Ensure all criteria have verification methods defined
+
+### Continuous Validation Integration
+
+Pre-Commit Validation:
+- Run SPEC linter before allowing commits
+- Block commits with validation errors
+- Generate validation reports for review
+- Suggest corrections for common issues
+
+CI/CD Integration:
+- Validate SPECs in pull request checks
+- Generate coverage reports for SPEC requirements
+- Track SPEC quality metrics over time
+- Alert on quality regression
+
+---
+
+## Workflow Optimization Strategies
+
+### Token Budget Optimization
+
+PLAN Phase Optimization:
+- Focus on requirement extraction efficiency
+- Use structured prompts for faster clarification
+- Minimize back-and-forth dialogue through comprehensive questions
+- Save SPEC document before context limit reached
+
+RUN Phase Optimization:
+- Load only relevant SPEC sections for current task
+- Use targeted test execution for faster feedback
+- Implement incremental TDD for large features
+- Clear context between major implementation phases
+
+SYNC Phase Optimization:
+- Generate documentation from structured SPEC data
+- Use templates for consistent documentation format
+- Batch multiple SPEC updates in single sync session
+- Automate changelog generation from SPEC metadata
+
+### Parallel Development Patterns
+
+Feature Independence Analysis:
+- Identify truly independent features for parallel work
+- Map shared dependencies that require coordination
+- Define integration points and contracts upfront
+- Establish merge order based on dependency graph
+
+Worktree Coordination:
+- Create separate worktrees for independent SPECs
+- Use feature flags for parallel integration
+- Define clear ownership boundaries per worktree
+- Schedule regular sync points for dependency updates
+
+Conflict Prevention:
+- Define interface contracts before parallel implementation
+- Use lock files for shared configuration changes
+- Implement automated conflict detection in CI
+- Document merge strategies for common conflict patterns
+
+---
+
+## Advanced Quality Patterns
+
+### SPEC Review Process
+
+Review Checklist:
+- All EARS patterns correctly applied
+- No ambiguous language present
+- All error cases documented
+- Performance targets quantified
+- Security requirements OWASP-compliant
+- Test scenarios cover all requirements
+- Success criteria measurable and verifiable
+
+Review Workflow:
+- Author creates SPEC draft
+- Reviewer validates against checklist
+- Author addresses review feedback
+- Final approval before implementation
+- Post-implementation verification
+
+### Quality Metrics Tracking
+
+SPEC Quality Indicators:
+- Requirement clarity score based on language analysis
+- Test coverage percentage for requirements
+- Constraint completeness assessment
+- Success criteria measurability rating
+
+Trend Analysis:
+- Track quality metrics over time
+- Identify common quality issues
+- Measure improvement from process changes
+- Generate team quality reports
+
+---
+
+## Integration Patterns
+
+### External System Integration
+
+Third-Party API Integration:
+- Define contract requirements in SPEC
+- Document expected response schemas
+- Include error handling for external failures
+- Specify timeout and retry requirements
+
+Database Schema Integration:
+- Document schema requirements in constraints
+- Define migration strategy for schema changes
+- Include rollback procedures for failed migrations
+- Specify data validation requirements
+
+Message Queue Integration:
+- Define message schemas in SPEC
+- Document delivery guarantees (at-least-once, exactly-once)
+- Include dead letter queue handling
+- Specify retry and timeout policies
+
+### Cross-SPEC Dependencies
+
+Dependency Documentation:
+- Use Related SPECs field for explicit dependencies
+- Document blocking and blocked-by relationships
+- Define integration contracts between SPECs
+- Specify integration testing requirements
+
+Dependency Management:
+- Create dependency graph for complex features
+- Identify critical path for prioritization
+- Track dependency completion status
+- Alert on blocked SPEC resolution
+
+---
+
+## Troubleshooting Advanced Issues
+
+### Complex Requirement Decomposition
+
+Problem: Requirement too complex for single EARS pattern
+Solution: Break into multiple atomic requirements, each with single pattern
+
+Problem: Requirements have implicit dependencies
+Solution: Make dependencies explicit with precondition documentation
+
+Problem: Requirements conflict with existing system behavior
+Solution: Document conflict and propose resolution strategy
+
+### Performance Optimization Issues
+
+Problem: SPEC processing takes too long
+Solution: Use progressive disclosure, load sections on demand
+
+Problem: Too many SPECs to manage effectively
+Solution: Group SPECs into Epics, use automated tracking
+
+Problem: SPEC drift from implementation
+Solution: Regular sync validation, automated drift detection
+
+---
+
+Version: 1.0.0
+Last Updated: 2025-12-07

moai_adk/templates/.claude/skills/moai-workflow-templates/SKILL.md

@@ -2,54 +2,77 @@
 name: moai-workflow-templates
 aliases: [moai-workflow-templates]
 description: Enterprise template management with code boilerplates, feedback templates, and project optimization workflows
-version: 3.0.0
+version: 3.1.0
 category: workflow
 modularized: true
+user-invocable: false
+tags:
+  [
+    "workflow",
+    "templates",
+    "boilerplate",
+    "scaffolding",
+    "optimization",
+    "feedback",
+  ]
+status: "active"
 replaces: moai-core-code-templates, moai-core-feedback-templates, moai-project-template-optimizer
-allowed-tools: Read, Write, Edit, Grep, Glob
+updated: 2026-01-11
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
 ---
 
 # Enterprise Template Management
 
 Unified template system combining code boilerplates, feedback templates, and project optimization workflows for rapid development and consistent patterns.
 
-## Quick Reference (30 seconds)
+## Quick Reference
 
 Core Capabilities:
-- Code template library (FastAPI, React, Vue, Next.js)
-- GitHub issue feedback templates (6 types)
+
+- Code template library for FastAPI, React, Vue, and Next.js
+- GitHub issue feedback templates covering 6 types
 - Project template optimization and smart merging
 - Template version management and history
 - Backup discovery and restoration
 - Pattern reusability and customization
 
 When to Use:
+
 - Scaffolding new projects or features
-- Creating GitHub issues with `/moai:9-feedback`
+- Creating GitHub issues with /moai:9-feedback
 - Optimizing template structures after MoAI-ADK updates
 - Restoring from project backups
 - Managing template versions and customizations
 - Generating boilerplate code
 
 Key Features:
-1. Code Templates: FastAPI, React, Vue, Docker, CI/CD
-2. Feedback Templates: 6 GitHub issue types (bug, feature, improvement, refactor, docs, question)
-3. Template Optimizer: Smart merge, backup restoration, version tracking
-4. Pattern Library: Reusable patterns for common scenarios
 
-Quick Access:
-- Code Templates → [code-templates.md](modules/code-templates.md)
-- Feedback Templates → [feedback-templates.md](modules/feedback-templates.md)
-- Template Optimizer → [template-optimizer.md](modules/template-optimizer.md)
+- Code Templates: FastAPI, React, Vue, Docker, and CI/CD templates
+- Feedback Templates: 6 GitHub issue types including bug, feature, improvement, refactor, docs, and question
+- Template Optimizer: Smart merge, backup restoration, and version tracking
+- Pattern Library: Reusable patterns for common scenarios
+
+Quick Access to Modules:
+
+- Code Templates documentation in modules/code-templates.md
+- Feedback Templates documentation in modules/feedback-templates.md
+- Template Optimizer documentation in modules/template-optimizer.md
 
-## Implementation Guide (5 minutes)
+## Implementation Guide
 
 ### Features
 
 - Project templates for common architectures
 - Boilerplate code generation with best practices
 - Configurable template variables and customization
-- Multi-framework support (React, FastAPI, Spring, etc.)
+- Multi-framework support including React, FastAPI, and Spring
 - Integrated testing and CI/CD configurations
 
 ### When to Use
@@ -62,69 +85,27 @@ Quick Access:
 
 ### Core Patterns
 
-Pattern 1: Template Structure
-```
-templates/
- fastapi-backend/
- template.json (variables)
- src/
- main.py
- models/
- tests/
- nextjs-frontend/
- template.json
- app/
- components/
- fullstack/
- backend/
- frontend/
-```
-
-Pattern 2: Template Variables
-```json
-{
- "variables": {
- "PROJECT_NAME": "my-project",
- "AUTHOR": "John Doe",
- "LICENSE": "MIT",
- "PYTHON_VERSION": "3.13"
- },
- "files": {
- "pyproject.toml": "substitute",
- "README.md": "substitute",
- "src//*.py": "copy"
- }
-}
-```
-
-Pattern 3: Template Generation
-```python
-def generate_from_template(template_name, variables):
- 1. Load template directory
- 2. Substitute variables in marked files
- 3. Copy static files as-is
- 4. Run post-generation hooks (install deps, init git)
- 5. Validate generated project structure
-```
-
-## 5 Core Patterns (5-10 minutes each)
+Pattern 1 - Template Structure:
+
+Templates are organized in a directory hierarchy. The top-level templates directory contains framework-specific subdirectories. A backend framework directory such as fastapi-backend contains template.json for variables and a src directory with main.py, models subdirectory, and tests subdirectory. A frontend framework directory such as nextjs-frontend contains template.json, app directory, and components directory. A fullstack template contains separate backend and frontend subdirectories.
+
+Pattern 2 - Template Variables:
+
+Template variables are defined in a JSON configuration file with two main sections. The variables section defines key-value pairs such as PROJECT_NAME, AUTHOR, LICENSE, and PYTHON_VERSION. The files section maps file patterns to processing modes: files marked as substitute have variables replaced, while files marked as copy are transferred unchanged.
+
+Pattern 3 - Template Generation:
+
+The template generation process follows five steps. First, load the template directory structure. Second, substitute variables in files marked for substitution. Third, copy static files as-is. Fourth, run post-generation hooks such as dependency installation and git initialization. Fifth, validate the generated project structure.
+
+## Core Patterns in Detail
 
 ### Pattern 1: Code Template Scaffolding
 
 Concept: Rapidly scaffold projects with production-ready boilerplates.
 
-Usage Example:
-```python
-# Generate FastAPI project structure
-template = load_template("backend/fastapi")
-project = template.scaffold(
- name="my-api",
- features=["auth", "database", "celery"],
- customizations={"db": "postgresql"}
-)
-```
+To generate a project, load the appropriate template such as backend/fastapi. Configure the scaffold with the project name, desired features such as auth, database, and celery, and customizations such as database type. Execute the scaffold to create the project structure.
 
-Details: See [Code Templates](modules/code-templates.md) for complete library and examples.
+For complete library and examples, see the Code Templates module documentation.
 
 ---
 
@@ -132,67 +113,31 @@ Details: See [Code Templates](modules/code-templates.md) for complete library an
 
 Concept: Structured templates for consistent GitHub issue creation.
 
-6 Template Types: Bug Report, Feature Request, Improvement, Refactor, Documentation, Question/Discussion
+Six Template Types: Bug Report, Feature Request, Improvement, Refactor, Documentation, and Question/Discussion.
 
-Integration: Auto-triggered by `/moai:9-feedback` command.
+Integration: Auto-triggered by the /moai:9-feedback command.
 
-Details: See [Feedback Templates](modules/feedback-templates.md) for all template types and usage.
+For all template types and usage, see the Feedback Templates module documentation.
 
 ---
 
-### Pattern 3: Template Optimization & Smart Merge
+### Pattern 3: Template Optimization and Smart Merge
 
 Concept: Intelligently merge template updates while preserving user customizations.
 
-Smart Merge Algorithm:
-```python
-def smart_merge(backup, template, current):
- """Three-way merge with intelligence."""
-
- # Extract user customizations from backup
- user_content = extract_user_customizations(backup)
-
- # Get latest template defaults
- template_defaults = get_current_templates()
-
- # Merge with priority
- merged = {
- "template_structure": template_defaults, # Always latest
- "user_config": user_content, # Preserved
- "custom_content": user_content # Extracted
- }
-
- return merged
-```
+Smart Merge Algorithm: The three-way merge process works as follows. First, extract user customizations from the backup. Second, get the latest template defaults from the current templates. Third, merge with appropriate priority where template_structure uses the latest defaults, user_config preserves user settings, and custom_content retains user modifications.
 
-Details: See [Template Optimizer](modules/template-optimizer.md) for complete workflow and examples.
+For complete workflow and examples, see the Template Optimizer module documentation.
 
 ---
 
-### Pattern 4: Backup Discovery & Restoration
+### Pattern 4: Backup Discovery and Restoration
 
 Concept: Automatic backup management with intelligent restoration.
 
-Restoration Process:
-```python
-def restore_from_backup(backup_id: str):
- """Restore project from specific backup."""
+Restoration Process: The process follows four steps. First, load backup metadata using the backup identifier. Second, validate backup integrity and raise an error if the backup is corrupted. Third, extract customizations from the validated backup. Fourth, apply the extracted customizations to the current project.
 
- # Load backup metadata
- backup = load_backup(backup_id)
-
- # Validate backup integrity
- if not validate_backup_integrity(backup):
- raise BackupIntegrityError("Backup corrupted")
-
- # Extract user customizations
- customizations = extract_customizations(backup)
-
- # Apply to current project
- apply_customizations(customizations)
-```
-
-Details: See [Template Optimizer - Backup Restoration](modules/template-optimizer.md#restoration-process) for complete implementation.
+For complete implementation, see the Template Optimizer module section on Restoration Process.
 
 ---
 
@@ -200,23 +145,9 @@ Details: See [Template Optimizer - Backup Restoration](modules/template-optimize
 
 Concept: Track template versions and maintain update history.
 
-Version Tracking:
-```json
-{
- "template_optimization": {
- "last_optimized": "2025-11-24T12:00:00Z",
- "backup_version": "backup-2025-10-15-v0.27.0",
- "template_version": "0.28.2",
- "customizations_preserved": [
- "language",
- "team_settings",
- "domains"
- ]
- }
-}
-```
-
-Details: See [Template Optimizer - Version Tracking](modules/template-optimizer.md#version-tracking) for complete implementation.
+Version Tracking: The template_optimization configuration section stores last_optimized timestamp, backup_version identifier, template_version number, and customizations_preserved list containing items like language, team_settings, and domains.
+
+For complete implementation, see the Template Optimizer module section on Version Tracking.
 
 ---
 
@@ -224,37 +155,21 @@ Details: See [Template Optimizer - Version Tracking](modules/template-optimizer.
 
 ### Core Modules
 
-- [Code Templates](modules/code-templates.md) - Boilerplate library, scaffold patterns, framework templates
-- [Feedback Templates](modules/feedback-templates.md) - 6 GitHub issue types, usage examples, best practices
-- [Template Optimizer](modules/template-optimizer.md) - Smart merge algorithm, backup restoration, version management
+- Code Templates in modules/code-templates.md: Boilerplate library, scaffold patterns, and framework templates
+- Feedback Templates in modules/feedback-templates.md: 6 GitHub issue types, usage examples, and best practices
+- Template Optimizer in modules/template-optimizer.md: Smart merge algorithm, backup restoration, and version management
 
 ### Module Contents
 
-Code Templates:
-- FastAPI REST API template
-- React component template
-- Docker & CI/CD templates
-- Template variables and scaffolding
-
-Feedback Templates:
-- Bug Report template
-- Feature Request template
-- Improvement, Refactor, Documentation, Question templates
-- Integration with `/moai:9-feedback`
-
-Template Optimizer:
-- 6-phase optimization workflow
-- Smart merge algorithm
-- Backup discovery and restoration
-- Version tracking and history
+Code Templates include FastAPI REST API template, React component template, Docker and CI/CD templates, and template variables with scaffolding patterns.
 
-## Advanced Documentation
+Feedback Templates include Bug Report template, Feature Request template, Improvement template, Refactor template, Documentation template, Question template, and integration with /moai:9-feedback command.
 
-For detailed patterns and implementation strategies:
+Template Optimizer includes 6-phase optimization workflow, smart merge algorithm, backup discovery and restoration, and version tracking with history.
 
-- [Code Templates Guide](modules/code-templates.md) - Complete template library
-- [Feedback Templates](modules/feedback-templates.md) - Issue template reference
-- [Template Optimizer](modules/template-optimizer.md) - Optimization and merge strategies
+## Advanced Documentation
+
+For detailed patterns and implementation strategies, refer to the Code Templates Guide for complete template library, Feedback Templates for issue template reference, and Template Optimizer for optimization and merge strategies.
 
 ## Best Practices
 
@@ -306,59 +221,35 @@ IMPACT: Without version tracking, teams cannot determine which template features
 ## Works Well With
 
 Agents:
-- workflow-project - Project initialization
-- core-planner - Template planning
-- workflow-spec - SPEC template generation
+
+- workflow-project: Project initialization
+- core-planner: Template planning
+- workflow-spec: SPEC template generation
 
 Skills:
-- moai-project-config-manager - Configuration management and validation
-- moai-cc-configuration - Claude Code settings integration
-- moai-foundation-specs - SPEC template generation
-- moai-docs-generation - Documentation template scaffolding
-- moai-core-workflow - Template-driven workflows
+
+- moai-project-config-manager: Configuration management and validation
+- moai-cc-configuration: Claude Code settings integration
+- moai-foundation-specs: SPEC template generation
+- moai-docs-generation: Documentation template scaffolding
+- moai-core-workflow: Template-driven workflows
 
 Commands:
-- `/moai:0-project` - Project initialization with templates
-- `/moai:9-feedback` - Feedback template selection and issue creation
+
+- /moai:0-project: Project initialization with templates
+- /moai:9-feedback: Feedback template selection and issue creation
 
 ## Workflow Integration
 
-Project Initialization:
-```
-1. Select code template (Pattern 1)
- ↓
-2. Scaffold project structure
- ↓
-3. Apply customizations
- ↓
-4. Initialize version tracking (Pattern 5)
-```
-
-Feedback Submission:
-```
-1. /moai:9-feedback execution
- ↓
-2. Select issue type (Pattern 2)
- ↓
-3. Fill template fields
- ↓
-4. Auto-generate GitHub issue
-```
-
-Template Update:
-```
-1. Detect template version change
- ↓
-2. Create backup (Pattern 4)
- ↓
-3. Run smart merge (Pattern 3)
- ↓
-4. Update version history (Pattern 5)
-```
+Project Initialization Workflow: Select code template using Pattern 1, scaffold project structure, apply customizations, and initialize version tracking using Pattern 5.
+
+Feedback Submission Workflow: Execute /moai:9-feedback command, select issue type using Pattern 2, fill template fields, and auto-generate GitHub issue.
+
+Template Update Workflow: Detect template version change, create backup using Pattern 4, run smart merge using Pattern 3, and update version history using Pattern 5.
 
 ## Success Metrics
 
-- Scaffold Time: 2 minutes for new projects (vs 30 minutes manual)
+- Scaffold Time: 2 minutes for new projects compared to 30 minutes manual
 - Template Adoption: 95% of projects use templates
 - Customization Preservation: 100% user content retained during updates
 - Feedback Completeness: 95% GitHub issues with complete information
@@ -366,6 +257,8 @@ Template Update:
 
 ## Changelog
 
+- v3.1.0 (2026-01-11): Converted to CLAUDE.md documentation standards, removed code blocks and tables
+- v3.0.0 (2026-01-08): Major version with modular architecture
 - v2.0.0 (2025-11-24): Unified moai-core-code-templates, moai-core-feedback-templates, and moai-project-template-optimizer into single skill with 5 core patterns
 - v1.0.0 (2025-11-22): Original individual skills