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

moai_adk/templates/.claude/skills/moai-alfred-interactive-questions/examples.md

@@ -0,0 +1,257 @@
+# moai-alfred-interactive-questions - Working Examples
+
+_Last updated: 2025-10-23_
+
+## Example 1: Simple Confirmation
+
+**Scenario**: Destructive operation (delete 50 user records)
+
+```typescript
+const answer = await AskUserQuestion({
+  questions: [{
+    question: "This will permanently delete 50 user records. Continue?",
+    header: "Confirm",
+    multiSelect: false,
+    options: [
+      { label: "Yes, proceed", description: "Irreversible operation. Delete now." },
+      { label: "No, cancel", description: "Abort and return." }
+    ]
+  }]
+});
+
+if (answer["Confirm"] === "Yes, proceed") {
+  // Execute deletion
+}
+```
+
+---
+
+## Example 2: Implementation Approach
+
+**Scenario**: "Add a completion page" (vague)
+
+```typescript
+const answer = await AskUserQuestion({
+  questions: [
+    {
+      question: "How should the completion page be implemented?",
+      header: "Approach",
+      multiSelect: false,
+      options: [
+        { label: "New public route", description: "Separate page at /competition-closed" },
+        { label: "Modify /end page", description: "Add conditional logic to existing page" },
+        { label: "Environment flag", description: "Use NEXT_PUBLIC_COMPETITION_CLOSED" }
+      ]
+    },
+    {
+      question: "For logged-in participants?",
+      header: "Behavior",
+      multiSelect: false,
+      options: [
+        { label: "Show results", description: "Redirect to /end with full history" },
+        { label: "Show message", description: "'Competition concluded' only" }
+      ]
+    }
+  ]
+});
+
+const approach = answer["Approach"];
+const behavior = answer["Behavior"];
+// Proceed with confirmed specifications
+```
+
+---
+
+## Example 3: Multi-Select (Independent Features)
+
+**Scenario**: "Which testing frameworks?"
+
+```typescript
+const answer = await AskUserQuestion({
+  questions: [{
+    question: "Which testing frameworks to include?",
+    header: "Test Tools",
+    multiSelect: true,  // User can select multiple
+    options: [
+      { label: "Unit tests (Vitest)", description: "Fast unit testing." },
+      { label: "E2E tests (Playwright)", description: "Browser automation." },
+      { label: "Visual regression", description: "Screenshot comparison." }
+    ]
+  }]
+});
+
+const selectedTools = answer["Test Tools"];  // ["Unit tests (Vitest)", "E2E tests (Playwright)"]
+// Install selected frameworks
+```
+
+---
+
+## Example 4: Sequential Questions (Conditional)
+
+**Scenario**: Q2 depends on Q1 answer
+
+```typescript
+// Question 1
+const q1 = await AskUserQuestion({
+  questions: [{
+    question: "Enable authentication?",
+    header: "Auth",
+    options: [
+      { label: "Yes", description: "User login required." },
+      { label: "No", description: "Public access." }
+    ]
+  }]
+});
+
+// Question 2 (only if Q1 = "Yes")
+if (q1["Auth"] === "Yes") {
+  const q2 = await AskUserQuestion({
+    questions: [{
+      question: "Which auth provider?",
+      header: "Provider",
+      options: [
+        { label: "JWT + email", description: "Traditional email/password." },
+        { label: "OAuth", description: "Third-party login (Google, GitHub)." }
+      ]
+    }]
+  });
+
+  const provider = q2["Provider"];
+  // Setup authentication
+}
+```
+
+---
+
+## Example 5: Feature Selection
+
+**Scenario**: "Which i18n library?"
+
+```typescript
+const answer = await AskUserQuestion({
+  questions: [{
+    question: "Which i18n library?",
+    header: "Library",
+    multiSelect: false,
+    options: [
+      { label: "next-intl", description: "Next.js 15+ native, best DX." },
+      { label: "react-i18next", description: "Popular, flexible, more setup." },
+      { label: "Format.js", description: "ICU format, complex but powerful." }
+    ]
+  }]
+});
+
+const library = answer["Library"];  // "next-intl"
+// Install and configure library
+```
+
+---
+
+## Example 6: Error Recovery
+
+**Scenario**: 3 tests failed, ask how to proceed
+
+```typescript
+const answer = await AskUserQuestion({
+  questions: [{
+    question: "3 tests failed in auth.test.ts. How should we proceed?",
+    header: "Test Failure",
+    multiSelect: false,
+    options: [
+      { label: "Debug immediately", description: "Stop and fix now." },
+      { label: "Skip tests", description: "NOT RECOMMENDED - continues with failing tests." },
+      { label: "Rollback changes", description: "Revert to last passing commit." }
+    ]
+  }]
+});
+
+if (answer["Test Failure"] === "Debug immediately") {
+  // Trigger debug workflow
+} else if (answer["Test Failure"] === "Rollback changes") {
+  // Rollback git changes
+}
+```
+
+---
+
+## Example 7: /alfred:1-plan Integration
+
+**Scenario**: spec-builder detects ambiguous SPEC title
+
+```typescript
+// Inside spec-builder
+function shouldAskForClarification(title: string): boolean {
+  return title.length < 20 || title.includes("feature/add/implement");
+}
+
+if (shouldAskForClarification(userTitle)) {
+  const answer = await AskUserQuestion({
+    questions: [{
+      question: "Can you clarify what this SPEC should cover?",
+      header: "Scope",
+      options: [
+        { label: "Authentication system", description: "User login, JWT tokens, refresh logic." },
+        { label: "UI components", description: "Reusable components library." },
+        { label: "API endpoints", description: "REST API implementation." }
+      ]
+    }]
+  });
+
+  specTitle = answer["Scope"];
+}
+```
+
+---
+
+## Example 8: /alfred:2-run Integration
+
+**Scenario**: code-builder detects multiple implementation paths
+
+```typescript
+// Inside code-builder
+if (multipleValidImplementationPaths) {
+  const answer = await AskUserQuestion({
+    questions: [{
+      question: "How should we implement JWT storage?",
+      header: "Storage",
+      options: [
+        { label: "HttpOnly cookie", description: "Most secure, no JS access." },
+        { label: "LocalStorage", description: "Accessible but vulnerable to XSS." },
+        { label: "Memory + refresh", description: "Balance between security and UX." }
+      ]
+    }]
+  });
+
+  const storageStrategy = answer["Storage"];
+  implementWithStrategy(storageStrategy);
+}
+```
+
+---
+
+## Example 9: /alfred:3-sync Integration
+
+**Scenario**: doc-syncer asks about sync mode
+
+```typescript
+// Inside doc-syncer
+const answer = await AskUserQuestion({
+  questions: [{
+    question: "Which sync mode?",
+    header: "Mode",
+    multiSelect: false,
+    options: [
+      { label: "auto", description: "Smart detection, sync affected docs only." },
+      { label: "force", description: "Regenerate all docs from scratch." },
+      { label: "status", description: "Show status without making changes." }
+    ]
+  }]
+});
+
+const syncMode = answer["Mode"];
+runSync(syncMode);
+```
+
+---
+
+For detailed guidance, see **SKILL.md** and **reference.md**

moai_adk/templates/.claude/skills/moai-alfred-interactive-questions/reference.md

@@ -0,0 +1,120 @@
+# moai-alfred-interactive-questions - Quick Reference
+
+_Last updated: 2025-10-23_
+
+## AskUserQuestion API Essentials
+
+### Minimal Template
+
+```typescript
+const answer = await AskUserQuestion({
+  questions: [
+    {
+      question: "Your question here?",
+      header: "Short label",  // max 12 chars
+      multiSelect: false,     // or true for multi-select
+      options: [
+        {
+          label: "Option 1",  // 1-5 words
+          description: "Why you'd pick this option."
+        },
+        {
+          label: "Option 2",
+          description: "Alternative with different implications."
+        }
+      ]
+    }
+  ]
+});
+
+// Access result
+const choice = answer["Short label"];  // "Option 1" or ["Option 1", "Option 2"]
+```
+
+---
+
+## When to Ask (Checklist)
+
+- [ ] User intent is ambiguous
+- [ ] Multiple valid implementation paths exist
+- [ ] Trade-off decision (speed vs quality, simple vs complete)
+- [ ] Risky/destructive operation needs approval
+- [ ] Feature scope needs definition
+
+---
+
+## Top 5 Patterns
+
+| Pattern | Use When | Example |
+|---------|----------|---------|
+| **Implementation Approach** | "Add feature X" without specifics | New component vs extend existing |
+| **Confirmation** | Destructive action (delete, migrate) | "Delete 50 records. Proceed?" |
+| **Feature Selection** | "Which framework/library?" | next-intl vs react-i18next |
+| **Multi-Select** | Independent combinable features | Unit + E2E + Visual tests |
+| **Sequential** | Dependent questions (Q2 depends on Q1) | Enable auth? → Which provider? |
+
+---
+
+## Key Constraints
+
+| What | Max | Why |
+|------|-----|-----|
+| Questions | 4 | Avoid fatigue |
+| Options | 4 | Prevent choice paralysis |
+| Header length | 12 chars | TUI layout |
+| Label length | 5 words | Quick scanning |
+| Nesting depth | 2 levels | Keep linear flow |
+
+---
+
+## Integration Points
+
+### spec-builder (`/alfred:1-plan`)
+Ask when SPEC title/scope is vague
+
+### code-builder (`/alfred:2-run`)
+Ask when implementation approach unclear or multiple paths exist
+
+### doc-syncer (`/alfred:3-sync`)
+Ask when sync mode or documentation scope unclear
+
+---
+
+## Error Handling
+
+```typescript
+// User cancels (ESC)
+try {
+  const answer = await AskUserQuestion({...});
+} catch (error) {
+  // Fallback or abort
+}
+
+// Validate custom input ("Other" option)
+if (!VALID_OPTIONS.includes(answer["Header"])) {
+  validateCustomInput(answer["Header"]);
+}
+```
+
+---
+
+## Best Practices (Quick)
+
+✅ **DO**:
+- Be specific ("Which database?" not "What should we use?")
+- Provide context (file names, scope, impact)
+- Explain trade-offs
+- Order logically (safest first)
+- Batch related questions
+
+❌ **DON'T**:
+- Overuse (only when ambiguous)
+- Too many options (2-4 max)
+- Skip descriptions
+- Hide implications
+- Make destructive default
+- Manually add "Other" (auto-provided)
+
+---
+
+For full details, see **SKILL.md**

moai_adk/templates/.claude/skills/moai-alfred-language-detection/SKILL.md

@@ -1,99 +1,113 @@
 ---
-
 name: moai-alfred-language-detection
-description: Detects the project’s primary language/runtime and recommends default testing tooling when initializing or planning workflows. Use when sizing up the project language and default tooling.
+version: 2.0.0
+created: 2025-10-22
+updated: 2025-10-22
+status: active
+description: Auto-detects project language and framework from package.json, pyproject.toml, etc.
+keywords: ['language', 'detection', 'framework', 'auto']
 allowed-tools:
   - Read
-  - Write
-  - Edit
   - Bash
-  - TodoWrite
 ---
 
-# Alfred Language Detection
+# Alfred Language Detection Skill
 
 ## Skill Metadata
+
 | Field | Value |
 | ----- | ----- |
-| Allowed tools | Read (read_file), Write (write_file), Edit (edit_file), Bash (terminal), TodoWrite (todo_write) |
-| Auto-load | /alfred:0-project bootstrap |
-| Trigger cues | Repository language probing, framework detection, tooling recommendation via Alfred. |
-
-## What it does
-
-Automatically detects project's primary language and framework by scanning configuration files, then recommends appropriate testing tools and linters.
-
-## When to use
-
-- Activates when Alfred needs to detect project languages or recommend toolchains.
-- "Detect language", "Check project language", "Recommend testing tools"
-- Automatically invoked by `/alfred:0-project`, `/alfred:2-run`
-- Setting up new project
-
-## How it works
-
-**Configuration File Scanning**:
-- `package.json` → TypeScript/JavaScript (Jest/Vitest, ESLint/Biome)
-- `pyproject.toml` → Python (pytest, ruff, black)
-- `Cargo.toml` → Rust (cargo test, clippy, rustfmt)
-- `go.mod` → Go (go test, golint, gofmt)
-- `Gemfile` → Ruby (RSpec, RuboCop)
-- `pubspec.yaml` → Dart/Flutter (flutter test, dart analyze)
-- `build.gradle` → Java/Kotlin (JUnit, Checkstyle)
-- `Package.swift` → Swift (XCTest, SwiftLint)
-
-**Toolchain Recommendation**:
-```json
-{
-  "language": "Python",
-  "test_framework": "pytest",
-  "linter": "ruff",
-  "formatter": "black",
-  "type_checker": "mypy",
-  "package_manager": "uv"
-}
-```
-
-**Framework Detection**:
-- **Python**: FastAPI, Django, Flask
-- **TypeScript**: React, Next.js, Vue
-- **Java**: Spring Boot, Quarkus
-
-**Supported Languages**: Python, TypeScript, Java, Go, Rust, Ruby, Dart, Swift, Kotlin, PHP, C#, C++, Elixir, Scala, Clojure (20+ languages)
+| **Skill Name** | moai-alfred-language-detection |
+| **Version** | 2.0.0 (2025-10-22) |
+| **Allowed tools** | Read (read_file), Bash (terminal) |
+| **Auto-load** | On demand when keywords detected |
+| **Tier** | Alfred |
 
-## Best Practices
-- The text shown to the user is written using TUI/report expressions.
-- When running the tool, a summary of commands and results are recorded.
+---
 
-## Examples
-```markdown
-- Call this skill inside the /alfred command to generate a report.
-- Add summary to Completion Report.
-```
+## What It Does
+
+Auto-detects project language and framework from package.json, pyproject.toml, etc.
+
+**Key capabilities**:
+- ✅ Best practices enforcement for alfred domain
+- ✅ TRUST 5 principles integration
+- ✅ Latest tool versions (2025-10-22)
+- ✅ TDD workflow support
+
+---
+
+## When to Use
+
+**Automatic triggers**:
+- Related code discussions and file patterns
+- SPEC implementation (`/alfred:2-run`)
+- Code review requests
+
+**Manual invocation**:
+- Review code for TRUST 5 compliance
+- Design new features
+- Troubleshoot issues
+
+---
 
 ## Inputs
-- MoAI-ADK project context (`.moai/project/`, `.claude/` templates, etc.).
-- Parameters passed from user commands or higher commands.
+
+- Language-specific source directories
+- Configuration files
+- Test suites and sample data
 
 ## Outputs
-- Reports, checklists or recommendations for your Alfred workflow.
-- Structured data for subsequent subagent calls.
+
+- Test/lint execution plan
+- TRUST 5 review checkpoints
+- Migration guidance
 
 ## Failure Modes
-- When required input documents are missing or permissions are limited.
-- When disruptive changes are required without user approval.
+
+- When required tools are not installed
+- When dependencies are missing
+- When test coverage falls below 85%
 
 ## Dependencies
-- Cooperation with higher-level agents such as cc-manager and project-manager is required.
 
-## References
-- GitHub Linguist. "Programmatic language detection." https://github.com/github-linguist/linguist (accessed 2025-03-29).
-- JetBrains. "Project language insights." https://www.jetbrains.com/help/idea/project-tool-window.html (accessed 2025-03-29).
+- Access to project files via Read/Bash tools
+- Integration with `moai-foundation-langs` for language detection
+- Integration with `moai-foundation-trust` for quality gates
+
+---
+
+## References (Latest Documentation)
+
+_Documentation links updated 2025-10-22_
+
+---
 
 ## Changelog
-- 2025-03-29: Added input/output/failure response to Alfred-specific skills.
 
-## Works well with
+- **v2.0.0** (2025-10-22): Major update with latest tool versions, comprehensive best practices, TRUST 5 integration
+- **v1.0.0** (2025-03-29): Initial Skill release
+
+---
+
+## Works Well With
+
+- `moai-foundation-trust` (quality gates)
+- `moai-alfred-code-reviewer` (code review)
+- `moai-essentials-debug` (debugging support)
+
+---
+
+## Best Practices
 
-- alfred-trust-validation (language-specific tool verification)
-- alfred-code-reviewer (language-specific review criteria)
+✅ **DO**:
+- Follow alfred best practices
+- Use latest stable tool versions
+- Maintain test coverage ≥85%
+- Document all public APIs
+
+❌ **DON'T**:
+- Skip quality gates
+- Use deprecated tools
+- Ignore security warnings
+- Mix testing frameworks

moai_adk/templates/.claude/skills/moai-alfred-language-detection/examples.md

@@ -0,0 +1,29 @@
+# moai-alfred-language-detection - Working Examples
+
+_Last updated: 2025-10-22_
+
+## Example 1: Basic Setup
+
+```bash
+# Setup commands
+# ...
+```
+
+## Example 2: TDD Workflow
+
+```bash
+# RED: Write failing test
+# GREEN: Implement feature
+# REFACTOR: Improve code
+```
+
+## Example 3: Quality Gate
+
+```bash
+# Run quality checks
+# Verify coverage ≥85%
+```
+
+---
+
+_For more examples, see SKILL.md reference section_

moai_adk/templates/.claude/skills/moai-alfred-language-detection/reference.md

@@ -0,0 +1,28 @@
+# moai-alfred-language-detection - CLI Reference
+
+_Last updated: 2025-10-22_
+
+## Quick Reference
+
+### Installation
+
+```bash
+# Installation commands
+```
+
+### Common Commands
+
+```bash
+# Test
+# Lint
+# Format
+# Build
+```
+
+## Tool Versions (2025-10-22)
+
+_No specific tool versions (workflow/process Skill)_
+
+---
+
+_For detailed usage, see SKILL.md_