moai-adk 0.4.4__py3-none-any.whl → 0.4.7__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-alfred-tui-survey/SKILL.md

@@ -1,87 +1,635 @@
 ---
-
 name: moai-alfred-tui-survey
-description: Standardizes Claude Code Tools AskUserQuestion TUI menus for surveys, branching approvals, and option picking across Alfred workflows. Use when gathering approvals or decisions via Alfred’s TUI menus.
+description: Standardizes Claude Code AskUserQuestion TUI menus for surveys, approvals, and option picking. Use when gathering user decisions, clarifying ambiguous requirements, or presenting implementation choices through interactive terminal menus.
 allowed-tools:
+  - AskUserQuestion
   - Read
-  - Write
-  - Edit
-  - TodoWrite
+  - Bash
+version: 2.0.0
+created: 2025-10-22
+updated: 2025-10-22
+status: active
+keywords: ['tui', 'survey', 'interactive', 'questions', 'menus', 'user-input', 'clarification', 'approval']
 ---
 
 # Alfred TUI Survey Skill
 
 ## Skill Metadata
+
 | Field | Value |
 | ----- | ----- |
-| Allowed tools | Read (read_file), Write (write_file), Edit (edit_file), TodoWrite (todo_write) |
-| Auto-load | On demand when AskUserQuestion menus are built |
-| Trigger cues | Branch approvals, survey menus, decision gating via AskUserQuestion. |
+| **Skill Name** | moai-alfred-tui-survey |
+| **Version** | 2.0.0 (2025-10-22) |
+| **Allowed tools** | AskUserQuestion (interactive surveys), Read (context), Bash (validation) |
+| **Auto-load** | On demand when ambiguity detected or approval needed |
+| **Tier** | Alfred |
+
+---
+
+## What It Does
+
+The **moai-alfred-tui-survey** Skill standardizes interactive user engagement through Claude Code's AskUserQuestion tool, transforming vague requests into precise specifications through structured TUI (Terminal User Interface) surveys.
+
+**Core Capabilities**:
+- Interactive clarification of ambiguous requirements
+- Structured decision-making for architectural choices
+- User approval workflows for critical operations
+- Multi-option selection menus with clear trade-offs
+- Context-aware question generation based on codebase analysis
+- Progressive disclosure of implementation options
+
+**Key Innovation**: Instead of AI guessing user intent from incomplete instructions ("Vibe Coding"), this Skill enables AI to present concrete options with clear trade-offs via terminal UI menus, capturing explicit user choices before execution.
+
+---
+
+## When to Use
+
+### Automatic Triggers
+
+This Skill activates automatically when:
+- **Ambiguity detected**: Multiple valid implementation approaches exist
+- **Architectural decisions**: Choice affects system design or data flow
+- **Breaking changes**: Operation may impact existing functionality
+- **User experience decisions**: Multiple UX patterns are viable
+- **Security/compliance**: Explicit approval required before proceeding
+
+### Manual Invocation
+
+Invoke explicitly when:
+- Planning complex features with trade-offs
+- Refactoring with multiple migration strategies
+- Designing APIs with competing patterns
+- Selecting libraries or frameworks
+- Clarifying high-level requirements like "Add a dashboard" or "Optimize performance"
+
+### Example Scenarios
+
+| User Request | Why TUI Survey Needed | Clarification Required |
+|--------------|----------------------|------------------------|
+| "Add a dashboard" | Multiple layout patterns exist | Layout type, data sources, authentication |
+| "Optimize performance" | Many bottlenecks possible | Target metric, acceptable trade-offs, profiling approach |
+| "Refactor auth system" | Multiple migration paths | Scope, backwards compatibility, deployment strategy |
+| "Add multi-language support" | Implementation varies widely | Scope (UI only vs full i18n), default language, library choice |
+
+---
+
+## Core Principles
+
+### 1. Reduce Ambiguity, Don't Guess
+
+**Problem**: Traditional "Vibe Coding" forces AI to infer intent from incomplete instructions, leading to:
+- Ambiguous implementations
+- Unnecessary code modifications
+- Multiple refinement rounds
+- Wasted developer time
 
-## What it does
+**Solution**: Present concrete options upfront, capture explicit choices, execute with certainty.
 
-Provides ready-to-use patterns for Claude Code's AskUserQuestion TUI selector so Alfred agents can gather user choices, approvals, or survey answers with structured menus instead of ad-hoc text prompts.
+### 2. Context-Aware Question Generation
 
-## When to use
+Survey questions are derived from:
+- Existing codebase patterns (`Read` tool analysis)
+- Current project structure (`Glob` for similar features)
+- Domain best practices (skill knowledge)
+- SPEC and TAG references (traceability context)
 
-- Activates when Alfred needs to gather structured choices through the TUI selector.
-- Need confirmation before advancing to a risky/destructive step.
-- Choosing between alternative implementation paths or automation levels.
-- Collecting survey-like answers (persona, tech stack, priority, risk level).
-- Any time a branched workflow depends on user-selected options rather than free-form text.
+### 3. Progressive Clarification
 
-## How it works
+Start with high-level choices, drill down based on selections:
+```
+Question 1: Implementation approach (architectural decision)
+    ↓
+Question 2: User experience details (UX decision)
+    ↓
+Question 3: Data handling strategy (technical decision)
+    ↓
+Review: Summary of all selections with "Go back" option
+```
+
+### 4. Always Provide Review Step
+
+Before executing, show summary:
+- All selected options
+- Implications of choices
+- Option to revise any answer
+- Clear "Submit" vs "Go back" actions
+
+---
+
+## TUI Survey Patterns
+
+### Pattern 1: Architectural Decision Survey
+
+**Use when**: Multiple system design approaches are viable
+
+**Structure**:
+```
+Question: "How should the [feature] be implemented?"
+Options:
+  - Approach A (description + trade-offs)
+  - Approach B (description + trade-offs)
+  - Approach C (description + trade-offs)
+  - [Other] (custom input)
+```
+
+**Example**:
+```
+Question: "How should the completion page be implemented?"
+Options:
+  1. Create new public page (/competition-closed)
+     • Unguarded route, visible to all visitors
+     • No authentication required
+     • PRO: Simple, clear separation | CON: Additional route
 
-1. **Detect gate** – Pause at steps that require explicit user choice.
-2. **Shape options** – Offer 2–5 focused choices with concise labels.
-3. **Render menu** – Emit the `AskUserQuestion({...})` block for the selector.
-4. **Map follow-ups** – Note how each option alters the next action/agent.
-5. **Fallback** – Provide plain-text instructions when the UI cannot render.
+  2. Modify existing /end page with conditional logic
+     • Check if competition is active before showing results
+     • PRO: Reuses existing code | CON: Adds complexity
 
-### Templates & examples
+  3. Use environment-based gating
+     • Set NEXT_PUBLIC_COMPETITION_CLOSED=true
+     • PRO: Runtime configuration | CON: Requires env management
+```
 
-- [Single-select deployment decision](examples.md#single-select-template)
-- [Multi-select diagnostics checklist](examples.md#multi-select-variation)
-- [Follow-up drill-down prompt](examples.md#follow-up-prompt-for-deeper-detail)
+### Pattern 2: Feature Scope Survey
 
-## Best Practices
-- Reduce context switching by putting questions, options, and follow-up actions on one screen.
-- Options are sorted according to comparison criteria such as risk and priority.
-- If safety measures are required, such as approval/suspension/cancellation, attach a warning message.
-- Submission results are recorded for reuse in the Sync step or reports.
+**Use when**: Feature scope is unclear or has multiple valid extents
 
-## Inputs
-- Decision scenarios and candidate options collected by Alfred workflows.
-- Definition of follow-up actions for each option (next command, subagent, TODO, etc.).
+**Structure**:
+```
+Question: "What scope should [feature] cover?"
+Options:
+  - Minimal (core functionality only)
+  - Standard (common use cases)
+  - Comprehensive (full feature set)
+  - [Other] (custom scope definition)
+```
+
+**Example**:
+```
+Question: "What scope should multi-language support cover?"
+Options:
+  1. UI labels only (buttons, menus, navigation)
+     • Scope: Frontend i18n | Effort: 2-3 days
+
+  2. UI + static content (about pages, help docs)
+     • Scope: Frontend + CMS integration | Effort: 5-7 days
+
+  3. Full i18n (UI, content, backend messages, emails)
+     • Scope: Full-stack internationalization | Effort: 10-14 days
+```
 
-## Outputs
-- AskUserQuestion block and choice → follow-up action mapping.
-- Summary of selection results and TODO items that require further confirmation.
+### Pattern 3: Technical Choice Survey
 
-## Failure Modes
-- Ambiguous or duplicate options cause selection delays.
-- It is difficult to judge priorities when all options look the same.
-- AskUserQuestion does not work in a TUI-inactive environment, so plan B is needed.
+**Use when**: Multiple libraries, frameworks, or tools can solve the problem
+
+**Structure**:
+```
+Question: "Which [tool/library] should be used for [purpose]?"
+Options:
+  - Option A (maturity, ecosystem, trade-offs)
+  - Option B (maturity, ecosystem, trade-offs)
+  - Option C (maturity, ecosystem, trade-offs)
+  - [Other] (specify alternative)
+```
+
+**Example**:
+```
+Question: "Which state management library should be used?"
+Options:
+  1. Redux Toolkit (v2.x)
+     • Maturity: Industry standard | Ecosystem: Extensive
+     • PRO: DevTools, middleware | CON: Boilerplate
+
+  2. Zustand (v5.x)
+     • Maturity: Stable, modern | Ecosystem: Growing
+     • PRO: Simple API, minimal boilerplate | CON: Fewer resources
+
+  3. Jotai (v2.x)
+     • Maturity: Modern atomic approach | Ecosystem: Niche
+     • PRO: Fine-grained reactivity | CON: Paradigm shift
+```
+
+### Pattern 4: Migration Strategy Survey
+
+**Use when**: Refactoring or upgrading with multiple migration paths
+
+**Structure**:
+```
+Question: "What migration strategy should be used?"
+Options:
+  - Big bang (full rewrite, single deployment)
+  - Incremental (gradual migration, feature flags)
+  - Parallel run (new + old systems coexist)
+  - [Other] (custom strategy)
+```
+
+**Example**:
+```
+Question: "How should the auth system be refactored?"
+Options:
+  1. Big bang migration (full rewrite)
+     • Timeline: 2-3 weeks | Risk: High
+     • PRO: Clean slate | CON: Risky deployment
+
+  2. Incremental with feature flags
+     • Timeline: 4-6 weeks | Risk: Medium
+     • PRO: Gradual rollout | CON: Code duplication
+
+  3. Parallel run (adapter pattern)
+     • Timeline: 6-8 weeks | Risk: Low
+     • PRO: Safe rollback | CON: Complex maintenance
+```
+
+### Pattern 5: Approval Workflow Survey
+
+**Use when**: Explicit approval needed before executing
+
+**Structure**:
+```
+Question: "Review the proposed changes. Proceed?"
+Options:
+  - Approve and execute
+  - Approve with modifications (specify)
+  - Reject and reconsider
+```
+
+**Example**:
+```
+Question: "This will delete 50 unused files. Proceed?"
+Details:
+  - 50 files identified as unused (last modified >6 months ago)
+  - Backup created at .moai-backups/pre-cleanup-2025-10-22
+  - Reversible via Git checkout
+
+Options:
+  1. Approve and execute cleanup
+  2. Review file list first (show details)
+  3. Cancel operation
+```
+
+---
+
+## Question Design Best Practices
+
+### Structure Each Question
+
+```yaml
+question: "Clear, specific question ending with ?"
+header: "Short label (max 12 chars)"  # e.g., "Auth method", "Library"
+multiSelect: false  # or true for checkboxes
+options:
+  - label: "Option 1 name"
+    description: "What this option means and its implications"
+  - label: "Option 2 name"
+    description: "What this option means and its implications"
+```
+
+### Writing Effective Questions
+
+**DO**:
+- ✅ Be specific: "How should the completion page be implemented?"
+- ✅ Provide context: Include current state, constraints, implications
+- ✅ Show trade-offs: PRO/CON, effort estimates, risk levels
+- ✅ Limit options: 2-4 main choices (avoid analysis paralysis)
+- ✅ Include "Other" option: Allow custom input
+- ✅ Use present tense: "How should...", "Which...", "What..."
+
+**DON'T**:
+- ❌ Be vague: "What do you want?" (too open-ended)
+- ❌ Use jargon without explanation: Assume user knowledge level
+- ❌ Omit implications: Show what each choice affects
+- ❌ Overload options: >4 options cause decision fatigue
+- ❌ Force choices: Always provide escape hatch
+- ❌ Use past tense: "How did you want...?" (sounds passive)
+
+### Option Design Patterns
+
+**Good Option Format**:
+```
+Option Label (concise, 3-7 words)
+  • Description of what this option does
+  • PRO: Key advantage | CON: Key limitation
+  • Effort: Time estimate | Risk: High/Medium/Low
+```
+
+**Example**:
+```
+Create new microservice
+  • Separate service with own database and API
+  • PRO: Full isolation, independent scaling
+  • CON: Operational overhead, network latency
+  • Effort: 2-3 weeks | Risk: Medium
+```
 
-## Dependencies
-- Works with the main `/alfred:*` command and schedules follow-up actions with TodoWrite when necessary.
-- When combined with moai-foundation-ears · moai-foundation-tags, requirements → options → TAG records are connected.
+### Multi-Select vs Single-Select
+
+**Single-Select** (default):
+- Use for mutually exclusive choices
+- Architecture patterns (can't be both monolith AND microservices)
+- Migration strategies (pick one path)
+- Primary library selection
+
+**Multi-Select** (`multiSelect: true`):
+- Use for independent, combinable options
+- Feature toggles (enable multiple features)
+- Validation rules (apply multiple checks)
+- Testing strategies (unit + integration + e2e)
+
+---
+
+## Integration with MoAI Workflow
+
+### Phase 1: Plan (`/alfred:1-plan`)
+
+**Use TUI Survey for**:
+- SPEC scope clarification ("What should this feature include?")
+- EARS pattern selection ("Which requirement type fits?")
+- TAG domain assignment ("Which domain does this belong to?")
+
+**Example**:
+```
+User: "/alfred:1-plan Add notification system"
+  ↓
+TUI Survey: "What type of notifications?"
+  - In-app only
+  - Email notifications
+  - Push notifications (mobile)
+  - All of the above
+  ↓
+TUI Survey: "Real-time or batch?"
+  - Real-time (WebSocket/SSE)
+  - Batch (scheduled jobs)
+  - Hybrid approach
+```
+
+### Phase 2: Run (`/alfred:2-run`)
+
+**Use TUI Survey for**:
+- Library/framework selection
+- Implementation approach (TDD RED → GREEN → REFACTOR)
+- Error handling strategy
+- Data validation approach
+
+**Example**:
+```
+User: "/alfred:2-run SPEC-001"
+  ↓
+TUI Survey: "Which validation library?"
+  - Zod (TypeScript-first)
+  - Yup (JSON schema)
+  - Joi (Node.js standard)
+  ↓
+Execute TDD cycle with selected library
+```
+
+### Phase 3: Sync (`/alfred:3-sync`)
+
+**Use TUI Survey for**:
+- Documentation language/format
+- Changelog structure
+- PR title/description style
+- Merge strategy
+
+**Example**:
+```
+User: "/alfred:3-sync"
+  ↓
+TUI Survey: "PR is ready. Merge strategy?"
+  - Squash and merge (clean history)
+  - Merge commit (preserve commits)
+  - Rebase and merge (linear history)
+  ↓
+Execute Git operations with selected strategy
+```
+
+---
+
+## AskUserQuestion Tool Specification
+
+### Tool Parameters
+
+```typescript
+{
+  questions: [
+    {
+      question: string,          // The question to ask
+      header: string,            // Short label (max 12 chars)
+      multiSelect: boolean,      // Allow multiple selections?
+      options: [
+        {
+          label: string,         // Option display text
+          description: string    // Explanation of option
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Response Format
+
+```typescript
+{
+  answers: {
+    [questionIndex: string]: string | string[]
+  }
+}
+```
+
+### Example Invocation
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      question: "How should the API authentication be implemented?",
+      header: "Auth method",
+      multiSelect: false,
+      options: [
+        {
+          label: "JWT with refresh tokens",
+          description: "Stateless auth with short-lived access tokens and long-lived refresh tokens"
+        },
+        {
+          label: "Session-based with cookies",
+          description: "Server-side sessions stored in Redis, client receives httpOnly cookie"
+        },
+        {
+          label: "OAuth2 with third-party provider",
+          description: "Delegate authentication to Google/GitHub/etc., receive tokens"
+        }
+      ]
+    },
+    {
+      question: "Which security features should be enabled?",
+      header: "Security",
+      multiSelect: true,
+      options: [
+        {
+          label: "Rate limiting",
+          description: "Prevent abuse with request rate limits per user/IP"
+        },
+        {
+          label: "CSRF protection",
+          description: "Protect against cross-site request forgery attacks"
+        },
+        {
+          label: "XSS prevention headers",
+          description: "Set Content-Security-Policy and X-Frame-Options headers"
+        }
+      ]
+    }
+  ]
+})
+```
+
+---
+
+## Failure Modes & Mitigation
+
+### Failure Mode 1: User Selects "Other" Without Details
+
+**Symptom**: User chooses "Other" but provides vague custom input
+
+**Mitigation**:
+- Follow up with clarifying questions
+- Provide examples of what details are needed
+- Show similar patterns from codebase for reference
+
+**Example**:
+```
+User selects: "Other: Something with webhooks"
+  ↓
+Follow-up TUI Survey:
+  "Could you clarify the webhook approach?"
+  - Outgoing webhooks (send events to external services)
+  - Incoming webhooks (receive events from external services)
+  - Bidirectional webhook system
+```
+
+### Failure Mode 2: Too Many Nested Questions
+
+**Symptom**: Survey becomes overwhelming with 5+ sequential questions
+
+**Mitigation**:
+- Limit to 3-4 questions per survey
+- Group related choices into single multi-select
+- Split complex decisions into multiple phases
+
+**Example**:
+```
+❌ BAD: 7 sequential questions about feature details
+
+✅ GOOD:
+  Phase 1: High-level approach (1-2 questions)
+  → Execute initial setup
+  Phase 2: Detailed configuration (1-2 questions)
+  → Finalize implementation
+```
+
+### Failure Mode 3: Options Not Mutually Exclusive
+
+**Symptom**: User wants to combine options marked as single-select
+
+**Mitigation**:
+- Review if multi-select is more appropriate
+- Add "Hybrid" or "Combination" option
+- Explain why options are mutually exclusive in descriptions
+
+**Example**:
+```
+Question: "Authentication strategy?"
+  - JWT only
+  - Session only
+  - Hybrid (JWT for API, sessions for web) ← Add this option
+```
+
+### Failure Mode 4: Insufficient Context in Questions
+
+**Symptom**: User can't make informed decision due to missing information
+
+**Mitigation**:
+- Always analyze codebase context before presenting survey (`Read` tool)
+- Include current state in question description
+- Show examples from existing code patterns
+
+**Example**:
+```
+Question: "How should error handling be implemented?"
+Context: "Current codebase uses try/catch blocks in 15 files,
+          Result<T, E> pattern in 5 files (services layer)."
+Options:
+  - Expand Result pattern (align with existing services)
+  - Standardize on try/catch (align with majority)
+  - Introduce error boundary pattern (new approach)
+```
+
+---
+
+## Best Practices Checklist
+
+### Before Creating Survey
+
+- [ ] Analyze codebase context (existing patterns, similar features)
+- [ ] Identify specific ambiguity or decision point
+- [ ] Verify that decision requires user input (not deterministic)
+- [ ] Check if similar decisions have been made before (consistency)
+
+### During Survey Design
+
+- [ ] Limit to 3-4 questions maximum
+- [ ] Each option has clear label + description
+- [ ] Trade-offs (PRO/CON) are visible when relevant
+- [ ] "Other" option is included for flexibility
+- [ ] Multi-select is used only for independent choices
+- [ ] Headers are concise (≤12 characters)
+
+### After Capturing Responses
+
+- [ ] Show review summary of all selections
+- [ ] Provide "Go back" option to revise
+- [ ] Confirm understanding with brief echo: "You selected [X], which means [Y]"
+- [ ] Log selections for future reference (SPEC, docs)
+
+---
+
+## Examples
+
+See [examples.md](examples.md) for complete real-world scenarios:
+1. **Competition Completion Page** - Architectural decision with scope clarification
+2. **State Management Library Selection** - Technical choice with trade-off analysis
+3. **Auth System Refactor** - Migration strategy with risk assessment
+4. **Feature Approval Workflow** - Explicit approval before destructive operation
+
+---
 
 ## References
-- Jakubovic, J. "Designing Effective CLI Dialogs." ACM Queue, 2021.
-- NCurses. "Programming Guide." https://invisible-island.net/ncurses/man/ncurses.3x.html (accessed 2025-03-29).
+
+See [reference.md](reference.md) for:
+- Complete AskUserQuestion API specification
+- TUI interaction patterns from popular frameworks
+- Decision tree templates for common scenarios
+- Integration points with Alfred sub-agents
+
+---
+
+## Works Well With
+
+- **moai-alfred-spec-metadata-validation**: Clarify SPEC scope during `/alfred:1-plan`
+- **moai-alfred-ears-authoring**: Select EARS patterns interactively
+- **moai-alfred-refactoring-coach**: Choose refactoring strategies
+- **moai-foundation-specs**: Confirm SPEC metadata choices
+
+---
 
 ## Changelog
-- 2025-03-29: Added input/output/failure response to Alfred-specific skills.
 
-## Works well with
+- **v2.0.0** (2025-10-22): Complete rewrite with TUI survey patterns, question design best practices, codebase context integration, failure mode analysis, and extensive examples
+- **v1.0.0** (2025-03-29): Initial Skill release with basic AskUserQuestion integration
 
-- `moai-foundation-ears` – Combine structured requirement patterns with menu-driven confirmations.
-- `moai-alfred-git-workflow` – Use menus to choose branch/worktree strategies.
-- `moai-alfred-code-reviewer` – Capture reviewer focus areas through guided selection.
+---
 
-## Examples
-```markdown
-- In the `/alfred:1-plan` step, user priorities are collected and the results are written to the PLAN board.
-- Check user approval before high-risk operations while running `/alfred:2-run`.
-```
+**Version**: 2.0.0
+**Last Updated**: 2025-10-22
+**Status**: Production-ready
+**Framework**: MoAI-ADK + Alfred workflow orchestration