moai-adk 0.4.7__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-cc-agents/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: "Creating and Managing Sub-agents in Claude Code"
+description: "Design agent personas, define proactive triggers, set tool permissions, structure agent files. Use when building specialized agents for code review, debugging, architecture, or domain-specific tasks."
+allowed-tools: "Read, Write, Edit, Glob, Bash"
+---
+
+# Creating and Managing Sub-agents
+
+Sub-agents are specialized Claude instances with independent context, custom prompts, and restricted tool access. They handle deep analysis, parallel work, and autonomous tasks.
+
+## Agent File Structure
+
+**Location**: `.claude/agents/`
+
+```yaml
+---
+name: agent-name
+description: Use PROACTIVELY for [specific trigger conditions]
+tools: Read, Write, Edit, Glob, Grep, Bash(git:*)
+model: sonnet
+---
+
+# Agent Name — Specialist Role
+
+Brief description of agent expertise.
+
+## Core Mission
+
+- Primary responsibility
+- Scope boundaries
+- Success criteria
+
+## Proactive Triggers
+
+- When to activate automatically
+- Specific conditions for invocation
+- Integration with workflow
+
+## Workflow Steps
+
+1. Input validation
+2. Task execution
+3. Output verification
+4. Handoff to next agent (if applicable)
+
+## Constraints
+
+- What NOT to do
+- Delegation rules
+- Quality gates
+```
+
+## Agent Persona Design Pattern
+
+```markdown
+---
+name: code-reviewer
+description: Use PROACTIVELY for code review requests, PR analysis, or quality checks
+tools: Read, Glob, Grep, Bash(git:*)
+model: sonnet
+---
+
+# Code Reviewer — Quality Expert
+
+Specialized in identifying code quality issues, security risks, and architecture concerns.
+
+## Core Mission
+
+- Review code for SOLID principles
+- Identify code smells and anti-patterns
+- Verify security best practices
+- Suggest improvements with rationale
+
+## Proactive Triggers
+
+- When user mentions "review", "quality", "audit"
+- After significant code changes
+- Before PR merge
+
+## Workflow Steps
+
+1. **Analyze**: Read changed files, understand context
+2. **Evaluate**: Check against TRUST 5 principles
+3. **Report**: List findings with severity & fix suggestions
+4. **Recommend**: Suggest refactoring or architectural improvements
+
+## Constraints
+
+- No direct edits (only suggestions)
+- Focus on maintainability, not style
+- Respect existing architecture decisions
+```
+
+## High-Freedom: Agent Principles
+
+### Autonomy & Expertise
+- Each agent owns 1 specialization (not 3+)
+- Define clear "when to activate" triggers
+- Agents should make decisions independently
+
+### Tool Access Minimization
+- Grant only necessary tools per role
+- Restrict Bash to specific commands: `Bash(git:*)`, `Bash(python:*)`
+- Never grant `Bash(*)`; always specify pattern
+
+### Handoff & Collaboration
+- Agent A completes → hands off to Agent B
+- Use clear "next agent" instructions
+- No circular dependencies
+
+## Medium-Freedom: Common Agent Patterns
+
+### Pattern 1: Debugger Agent
+```yaml
+name: debugger
+description: Use PROACTIVELY for error diagnosis, test failures, exception analysis
+tools: Read, Grep, Glob, Bash(pytest:*), Bash(git:*)
+model: sonnet
+```
+
+**Mission**: Diagnose errors, provide fix-forward guidance
+**Triggers**: `error`, `failed`, `exception`, `debug`
+**Output**: Root cause + suggested fixes
+
+### Pattern 2: Architect Agent
+```yaml
+name: architect
+description: Use PROACTIVELY for system design, refactoring, scalability concerns
+tools: Read, Glob, Grep, Bash(ls:*), Bash(find:*)
+model: sonnet
+```
+
+**Mission**: Design systems, propose architectures
+**Triggers**: `architecture`, `refactor`, `design`, `scalability`
+**Output**: Design document + implementation roadmap
+
+### Pattern 3: Security Agent
+```yaml
+name: security-auditor
+description: Use PROACTIVELY for vulnerability assessment, OWASP checks, secrets detection
+tools: Read, Glob, Grep
+model: sonnet
+```
+
+**Mission**: Find security issues, verify OWASP compliance
+**Triggers**: `security`, `audit`, `vulnerability`, `secrets`
+**Output**: Risk assessment + remediation steps
+
+## Low-Freedom: Tool Permission Patterns
+
+### Principle of Least Privilege
+
+```yaml
+# ❌ Too permissive
+tools: Read, Write, Edit, Bash(*)
+
+# ✅ Appropriate
+tools: Read, Glob, Grep  # Read-only analysis
+
+# ✅ Appropriate
+tools: Read, Edit, Bash(black:*), Bash(pytest:*)  # Formatter + tests only
+```
+
+### Bash Command Restrictions
+
+```yaml
+# Allowed patterns:
+Bash(git:*)           # All git commands
+Bash(npm run:*)       # Only npm run scripts
+Bash(python:*)        # Python interpreter
+Bash(pytest:*)        # Pytest runner
+
+# Denied patterns:
+Bash(rm:*)            # Dangerous deletion
+Bash(sudo:*)          # Privilege escalation
+Bash(curl:*)          # Arbitrary downloads
+```
+
+## Agent Execution Modes
+
+### Mode 1: Inline (main context)
+```bash
+/role security
+"Check this project for vulnerabilities"
+# Runs in main session context
+```
+
+### Mode 2: Sub-agent (isolated context)
+```bash
+/role security --agent
+"Perform comprehensive security audit"
+# Runs in independent context, can work in parallel
+```
+
+### Mode 3: Parallel Multi-role
+```bash
+/multi-role security,performance,qa --agent
+"Analyze security, performance, and quality"
+# All roles run in parallel, results merged
+```
+
+## Agent Registration & Discovery
+
+```bash
+# List available agents
+/agents
+
+# Create new agent interactively
+/agents create
+
+# View specific agent
+/agents view security-auditor
+
+# Edit agent
+/agents edit security-auditor
+
+# Delete agent
+/agents delete security-auditor
+```
+
+## Agent Validation Checklist
+
+- [ ] `name` is kebab-case (e.g., `code-reviewer`)
+- [ ] `description` includes "Use PROACTIVELY for"
+- [ ] `tools` list only necessary tools
+- [ ] No `Bash(*)` wildcard; specific patterns only
+- [ ] `model` is `haiku` or `sonnet`
+- [ ] `Proactive Triggers` section clearly defined
+- [ ] No overlapping responsibilities with other agents
+- [ ] YAML frontmatter is valid
+
+## Best Practices
+
+✅ **DO**:
+- Design agents around specific expertise
+- Use `--agent` flag for large analyses
+- Combine multiple agents for complex tasks
+- Name agents descriptively
+
+❌ **DON'T**:
+- Create overpowered agents with all tools
+- Allow direct file modifications without approval
+- Overlap agent responsibilities
+- Use `Bash(*)` without specific patterns
+
+---
+
+**Reference**: Claude Code Sub-agents documentation
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-cc-agents/templates/agent-template.md

@@ -0,0 +1,32 @@
+---
+name: agent-name
+description: Use PROACTIVELY for [specific trigger conditions]
+tools: Read, Glob, Grep, Bash(git:*)
+model: sonnet
+---
+
+# Agent Name — Specialist Role
+
+Brief description of agent expertise.
+
+## Core Mission
+
+- Primary responsibility
+- Scope boundaries
+- Success criteria
+
+## Proactive Triggers
+
+- When to activate automatically
+- Specific conditions for invocation
+
+## Workflow Steps
+
+1. Input validation
+2. Task execution
+3. Output verification
+
+## Constraints
+
+- What NOT to do
+- Delegation rules