1# Interactive Command Patterns
2 
3Comprehensive guide to creating commands that gather user feedback and make decisions through the AskUserQuestion tool.
4 
5## Overview
6 
7Some commands need user input that doesn't work well with simple arguments. For example:
8- Choosing between multiple complex options with trade-offs
9- Selecting multiple items from a list
10- Making decisions that require explanation
11- Gathering preferences or configuration interactively
12 
13For these cases, use the **AskUserQuestion tool** within command execution rather than relying on command arguments.
14 
15## When to Use AskUserQuestion
16 
17### Use AskUserQuestion When:
18 
191. **Multiple choice decisions** with explanations needed
202. **Complex options** that require context to choose
213. **Multi-select scenarios** (choosing multiple items)
224. **Preference gathering** for configuration
235. **Interactive workflows** that adapt based on answers
24 
25### Use Command Arguments When:
26 
271. **Simple values** (file paths, numbers, names)
282. **Known inputs** user already has
293. **Scriptable workflows** that should be automatable
304. **Fast invocations** where prompting would slow down
31 
32## AskUserQuestion Basics
33 
34### Tool Parameters
35 
36```typescript
37{
38  questions: [
39    {
40      question: "Which authentication method should we use?",
41      header: "Auth method",  // Short label (max 12 chars)
42      multiSelect: false,     // true for multiple selection
43      options: [
44        {
45          label: "OAuth 2.0",
46          description: "Industry standard, supports multiple providers"
47        },
48        {
49          label: "JWT",
50          description: "Stateless, good for APIs"
51        },
52        {
53          label: "Session",
54          description: "Traditional, server-side state"
55        }
56      ]
57    }
58  ]
59}
60```
61 
62**Key points:**
63- Users can always choose "Other" to provide custom input (automatic)
64- `multiSelect: true` allows selecting multiple options
65- Options should be 2-4 choices (not more)
66- Can ask 1-4 questions per tool call
67 
68## Command Pattern for User Interaction
69 
70### Basic Interactive Command
71 
72```markdown
73---
74description: Interactive setup command
75allowed-tools: AskUserQuestion, Write
76---
77 
78# Interactive Plugin Setup
79 
80This command will guide you through configuring the plugin with a series of questions.
81 
82## Step 1: Gather Configuration
83 
84Use the AskUserQuestion tool to ask:
85 
86**Question 1 - Deployment target:**
87- header: "Deploy to"
88- question: "Which deployment platform will you use?"
89- options:
90  - AWS (Amazon Web Services with ECS/EKS)
91  - GCP (Google Cloud with GKE)
92  - Azure (Microsoft Azure with AKS)
93  - Local (Docker on local machine)
94 
95**Question 2 - Environment strategy:**
96- header: "Environments"
97- question: "How many environments do you need?"
98- options:
99  - Single (Just production)
100  - Standard (Dev, Staging, Production)
101  - Complete (Dev, QA, Staging, Production)
102 
103**Question 3 - Features to enable:**
104- header: "Features"
105- question: "Which features do you want to enable?"
106- multiSelect: true
107- options:
108  - Auto-scaling (Automatic resource scaling)
109  - Monitoring (Health checks and metrics)
110  - CI/CD (Automated deployment pipeline)
111  - Backups (Automated database backups)
112 
113## Step 2: Process Answers
114 
115Based on the answers received from AskUserQuestion:
116 
1171. Parse the deployment target choice
1182. Set up environment-specific configuration
1193. Enable selected features
1204. Generate configuration files
121 
122## Step 3: Generate Configuration
123 
124Create `.claude/plugin-name.local.md` with:
125 
126\`\`\`yaml
127---
128deployment_target: [answer from Q1]
129environments: [answer from Q2]
130features:
131  auto_scaling: [true if selected in Q3]
132  monitoring: [true if selected in Q3]
133  ci_cd: [true if selected in Q3]
134  backups: [true if selected in Q3]
135---
136 
137# Plugin Configuration
138 
139Generated: [timestamp]
140Target: [deployment_target]
141Environments: [environments]
142\`\`\`
143 
144## Step 4: Confirm and Next Steps
145 
146Confirm configuration created and guide user on next steps.
147```
148 
149### Multi-Stage Interactive Workflow
150 
151```markdown
152---
153description: Multi-stage interactive workflow
154allowed-tools: AskUserQuestion, Read, Write, Bash
155---
156 
157# Multi-Stage Deployment Setup
158 
159This command walks through deployment setup in stages, adapting based on your answers.
160 
161## Stage 1: Basic Configuration
162 
163Use AskUserQuestion to ask about deployment basics.
164 
165Based on answers, determine which additional questions to ask.
166 
167## Stage 2: Advanced Options (Conditional)
168 
169If user selected "Advanced" deployment in Stage 1:
170 
171Use AskUserQuestion to ask about:
172- Load balancing strategy
173- Caching configuration
174- Security hardening options
175 
176If user selected "Simple" deployment:
177- Skip advanced questions
178- Use sensible defaults
179 
180## Stage 3: Confirmation
181 
182Show summary of all selections.
183 
184Use AskUserQuestion for final confirmation:
185- header: "Confirm"
186- question: "Does this configuration look correct?"
187- options:
188  - Yes (Proceed with setup)
189  - No (Start over)
190  - Modify (Let me adjust specific settings)
191 
192If "Modify", ask which specific setting to change.
193 
194## Stage 4: Execute Setup
195 
196Based on confirmed configuration, execute setup steps.
197```
198 
199## Interactive Question Design
200 
201### Question Structure
202 
203**Good questions:**
204```markdown
205Question: "Which database should we use for this project?"
206Header: "Database"
207Options:
208  - PostgreSQL (Relational, ACID compliant, best for complex queries)
209  - MongoDB (Document store, flexible schema, best for rapid iteration)
210  - Redis (In-memory, fast, best for caching and sessions)
211```
212 
213**Poor questions:**
214```markdown
215Question: "Database?"  // Too vague
216Header: "DB"  // Unclear abbreviation
217Options:
218  - Option 1  // Not descriptive
219  - Option 2
220```
221 
222### Option Design Best Practices
223 
224**Clear labels:**
225- Use 1-5 words
226- Specific and descriptive
227- No jargon without context
228 
229**Helpful descriptions:**
230- Explain what the option means
231- Mention key benefits or trade-offs
232- Help user make informed decision
233- Keep to 1-2 sentences
234 
235**Appropriate number:**
236- 2-4 options per question
237- Don't overwhelm with too many choices
238- Group related options
239- "Other" automatically provided
240 
241### Multi-Select Questions
242 
243**When to use multiSelect:**
244 
245```markdown
246Use AskUserQuestion for enabling features:
247 
248Question: "Which features do you want to enable?"
249Header: "Features"
250multiSelect: true  // Allow selecting multiple
251Options:
252  - Logging (Detailed operation logs)
253  - Metrics (Performance monitoring)
254  - Alerts (Error notifications)
255  - Backups (Automatic backups)
256```
257 
258User can select any combination: none, some, or all.
259 
260**When NOT to use multiSelect:**
261 
262```markdown
263Question: "Which authentication method?"
264multiSelect: false  // Only one auth method makes sense
265```
266 
267Mutually exclusive choices should not use multiSelect.
268 
269## Command Patterns with AskUserQuestion
270 
271### Pattern 1: Simple Yes/No Decision
272 
273```markdown
274---
275description: Command with confirmation
276allowed-tools: AskUserQuestion, Bash
277---
278 
279# Destructive Operation
280 
281This operation will delete all cached data.
282 
283Use AskUserQuestion to confirm:
284 
285Question: "This will delete all cached data. Are you sure?"
286Header: "Confirm"
287Options:
288  - Yes (Proceed with deletion)
289  - No (Cancel operation)
290 
291If user selects "Yes":
292  Execute deletion
293  Report completion
294 
295If user selects "No":
296  Cancel operation
297  Exit without changes
298```
299 
300### Pattern 2: Multiple Configuration Questions
301 
302```markdown
303---
304description: Multi-question configuration
305allowed-tools: AskUserQuestion, Write
306---
307 
308# Project Configuration Setup
309 
310Gather configuration through multiple questions.
311 
312Use AskUserQuestion with multiple questions in one call:
313 
314**Question 1:**
315- question: "Which programming language?"
316- header: "Language"
317- options: Python, TypeScript, Go, Rust
318 
319**Question 2:**
320- question: "Which test framework?"
321- header: "Testing"
322- options: Jest, PyTest, Go Test, Cargo Test
323  (Adapt based on language from Q1)
324 
325**Question 3:**
326- question: "Which CI/CD platform?"
327- header: "CI/CD"
328- options: GitHub Actions, GitLab CI, CircleCI
329 
330**Question 4:**
331- question: "Which features do you need?"
332- header: "Features"
333- multiSelect: true
334- options: Linting, Type checking, Code coverage, Security scanning
335 
336Process all answers together to generate cohesive configuration.
337```
338 
339### Pattern 3: Conditional Question Flow
340 
341```markdown
342---
343description: Conditional interactive workflow
344allowed-tools: AskUserQuestion, Read, Write
345---
346 
347# Adaptive Configuration
348 
349## Question 1: Deployment Complexity
350 
351Use AskUserQuestion:
352 
353Question: "How complex is your deployment?"
354Header: "Complexity"
355Options:
356  - Simple (Single server, straightforward)
357  - Standard (Multiple servers, load balancing)
358  - Complex (Microservices, orchestration)
359 
360## Conditional Questions Based on Answer
361 
362If answer is "Simple":
363  - No additional questions
364  - Use minimal configuration
365 
366If answer is "Standard":
367  - Ask about load balancing strategy
368  - Ask about scaling policy
369 
370If answer is "Complex":
371  - Ask about orchestration platform (Kubernetes, Docker Swarm)
372  - Ask about service mesh (Istio, Linkerd, None)
373  - Ask about monitoring (Prometheus, Datadog, CloudWatch)
374  - Ask about logging aggregation
375 
376## Process Conditional Answers
377 
378Generate configuration appropriate for selected complexity level.
379```
380 
381### Pattern 4: Iterative Collection
382 
383```markdown
384---
385description: Collect multiple items iteratively
386allowed-tools: AskUserQuestion, Write
387---
388 
389# Collect Team Members
390 
391We'll collect team member information for the project.
392 
393## Question: How many team members?
394 
395Use AskUserQuestion:
396 
397Question: "How many team members should we set up?"
398Header: "Team size"
399Options:
400  - 2 people
401  - 3 people
402  - 4 people
403  - 6 people
404 
405## Iterate Through Team Members
406 
407For each team member (1 to N based on answer):
408 
409Use AskUserQuestion for member details:
410 
411Question: "What role for team member [number]?"
412Header: "Role"
413Options:
414  - Frontend Developer
415  - Backend Developer
416  - DevOps Engineer
417  - QA Engineer
418  - Designer
419 
420Store each member's information.
421 
422## Generate Team Configuration
423 
424After collecting all N members, create team configuration file with all members and their roles.
425```
426 
427### Pattern 5: Dependency Selection
428 
429```markdown
430---
431description: Select dependencies with multi-select
432allowed-tools: AskUserQuestion
433---
434 
435# Configure Project Dependencies
436 
437## Question: Required Libraries
438 
439Use AskUserQuestion with multiSelect:
440 
441Question: "Which libraries does your project need?"
442Header: "Dependencies"
443multiSelect: true
444Options:
445  - React (UI framework)
446  - Express (Web server)
447  - TypeORM (Database ORM)
448  - Jest (Testing framework)
449  - Axios (HTTP client)
450 
451User can select any combination.
452 
453## Process Selections
454 
455For each selected library:
456- Add to package.json dependencies
457- Generate sample configuration
458- Create usage examples
459- Update documentation
460```
461 
462## Best Practices for Interactive Commands
463 
464### Question Design
465 
4661. **Clear and specific**: Question should be unambiguous
4672. **Concise header**: Max 12 characters for clean display
4683. **Helpful options**: Labels are clear, descriptions explain trade-offs
4694. **Appropriate count**: 2-4 options per question, 1-4 questions per call
4705. **Logical order**: Questions flow naturally
471 
472### Error Handling
473 
474```markdown
475# Handle AskUserQuestion Responses
476 
477After calling AskUserQuestion, verify answers received:
478 
479If answers are empty or invalid:
480  Something went wrong gathering responses.
481 
482  Please try again or provide configuration manually:
483  [Show alternative approach]
484 
485  Exit.
486 
487If answers look correct:
488  Process as expected
489```
490 
491### Progressive Disclosure
492 
493```markdown
494# Start Simple, Get Detailed as Needed
495 
496## Question 1: Setup Type
497 
498Use AskUserQuestion:
499 
500Question: "How would you like to set up?"
501Header: "Setup type"
502Options:
503  - Quick (Use recommended defaults)
504  - Custom (Configure all options)
505  - Guided (Step-by-step with explanations)
506 
507If "Quick":
508  Apply defaults, minimal questions
509 
510If "Custom":
511  Ask all available configuration questions
512 
513If "Guided":
514  Ask questions with extra explanation
515  Provide recommendations along the way
516```
517 
518### Multi-Select Guidelines
519 
520**Good multi-select use:**
521```markdown
522Question: "Which features do you want to enable?"
523multiSelect: true
524Options:
525  - Logging
526  - Metrics
527  - Alerts
528  - Backups
529 
530Reason: User might want any combination
531```
532 
533**Bad multi-select use:**
534```markdown
535Question: "Which database engine?"
536multiSelect: true  // ❌ Should be single-select
537 
538Reason: Can only use one database engine
539```
540 
541## Advanced Patterns
542 
543### Validation Loop
544 
545```markdown
546---
547description: Interactive with validation
548allowed-tools: AskUserQuestion, Bash
549---
550 
551# Setup with Validation
552 
553## Gather Configuration
554 
555Use AskUserQuestion to collect settings.
556 
557## Validate Configuration
558 
559Check if configuration is valid:
560- Required dependencies available?
561- Settings compatible with each other?
562- No conflicts detected?
563 
564If validation fails:
565  Show validation errors
566 
567  Use AskUserQuestion to ask:
568 
569  Question: "Configuration has issues. What would you like to do?"
570  Header: "Next step"
571  Options:
572    - Fix (Adjust settings to resolve issues)
573    - Override (Proceed despite warnings)
574    - Cancel (Abort setup)
575 
576  Based on answer, retry or proceed or exit.
577```
578 
579### Build Configuration Incrementally
580 
581```markdown
582---
583description: Incremental configuration builder
584allowed-tools: AskUserQuestion, Write, Read
585---
586 
587# Incremental Setup
588 
589## Phase 1: Core Settings
590 
591Use AskUserQuestion for core settings.
592 
593Save to `.claude/config-partial.yml`
594 
595## Phase 2: Review Core Settings
596 
597Show user the core settings:
598 
599Based on these core settings, you need to configure:
600- [Setting A] (because you chose [X])
601- [Setting B] (because you chose [Y])
602 
603Ready to continue?
604 
605## Phase 3: Detailed Settings
606 
607Use AskUserQuestion for settings based on Phase 1 answers.
608 
609Merge with core settings.
610 
611## Phase 4: Final Review
612 
613Present complete configuration.
614 
615Use AskUserQuestion for confirmation:
616 
617Question: "Is this configuration correct?"
618Options:
619  - Yes (Save and apply)
620  - No (Start over)
621  - Modify (Edit specific settings)
622```
623 
624### Dynamic Options Based on Context
625 
626```markdown
627---
628description: Context-aware questions
629allowed-tools: AskUserQuestion, Bash, Read
630---
631 
632# Context-Aware Setup
633 
634## Detect Current State
635 
636Check existing configuration:
637- Current language: !`detect-language.sh`
638- Existing frameworks: !`detect-frameworks.sh`
639- Available tools: !`check-tools.sh`
640 
641## Ask Context-Appropriate Questions
642 
643Based on detected language, ask relevant questions.
644 
645If language is TypeScript:
646 
647  Use AskUserQuestion:
648 
649  Question: "Which TypeScript features should we enable?"
650  Options:
651    - Strict Mode (Maximum type safety)
652    - Decorators (Experimental decorator support)
653    - Path Mapping (Module path aliases)
654 
655If language is Python:
656 
657  Use AskUserQuestion:
658 
659  Question: "Which Python tools should we configure?"
660  Options:
661    - Type Hints (mypy for type checking)
662    - Black (Code formatting)
663    - Pylint (Linting and style)
664 
665Questions adapt to project context.
666```
667 
668## Real-World Example: Multi-Agent Swarm Launch
669 
670**From multi-agent-swarm plugin:**
671 
672```markdown
673---
674description: Launch multi-agent swarm
675allowed-tools: AskUserQuestion, Read, Write, Bash
676---
677 
678# Launch Multi-Agent Swarm
679 
680## Interactive Mode (No Task List Provided)
681 
682If user didn't provide task list file, help create one interactively.
683 
684### Question 1: Agent Count
685 
686Use AskUserQuestion:
687 
688Question: "How many agents should we launch?"
689Header: "Agent count"
690Options:
691  - 2 agents (Best for simple projects)
692  - 3 agents (Good for medium projects)
693  - 4 agents (Standard team size)
694  - 6 agents (Large projects)
695  - 8 agents (Complex multi-component projects)
696 
697### Question 2: Task Definition Approach
698 
699Use AskUserQuestion:
700 
701Question: "How would you like to define tasks?"
702Header: "Task setup"
703Options:
704  - File (I have a task list file ready)
705  - Guided (Help me create tasks interactively)
706  - Custom (Other approach)
707 
708If "File":
709  Ask for file path
710  Validate file exists and has correct format
711 
712If "Guided":
713  Enter iterative task creation mode (see below)
714 
715### Question 3: Coordination Mode
716 
717Use AskUserQuestion:
718 
719Question: "How should agents coordinate?"
720Header: "Coordination"
721Options:
722  - Team Leader (One agent coordinates others)
723  - Collaborative (Agents coordinate as peers)
724  - Autonomous (Independent work, minimal coordination)
725 
726### Iterative Task Creation (If "Guided" Selected)
727 
728For each agent (1 to N from Question 1):
729 
730**Question A: Agent Name**
731Question: "What should we call agent [number]?"
732Header: "Agent name"
733Options:
734  - auth-agent
735  - api-agent
736  - ui-agent
737  - db-agent
738  (Provide relevant suggestions based on common patterns)
739 
740**Question B: Task Type**
741Question: "What task for [agent-name]?"
742Header: "Task type"
743Options:
744  - Authentication (User auth, JWT, OAuth)
745  - API Endpoints (REST/GraphQL APIs)
746  - UI Components (Frontend components)
747  - Database (Schema, migrations, queries)
748  - Testing (Test suites and coverage)
749  - Documentation (Docs, README, guides)
750 
751**Question C: Dependencies**
752Question: "What does [agent-name] depend on?"
753Header: "Dependencies"
754multiSelect: true
755Options:
756  - [List of previously defined agents]
757  - No dependencies
758 
759**Question D: Base Branch**
760Question: "Which base branch for PR?"
761Header: "PR base"
762Options:
763  - main
764  - staging
765  - develop
766 
767Store all task information for each agent.
768 
769### Generate Task List File
770 
771After collecting all agent task details:
772 
7731. Ask for project name
7742. Generate task list in proper format
7753. Save to `.daisy/swarm/tasks.md`
7764. Show user the file path
7775. Proceed with launch using generated task list
778```
779 
780## Best Practices
781 
782### Question Writing
783 
7841. **Be specific**: "Which database?" not "Choose option?"
7852. **Explain trade-offs**: Describe pros/cons in option descriptions
7863. **Provide context**: Question text should stand alone
7874. **Guide decisions**: Help user make informed choice
7885. **Keep concise**: Header max 12 chars, descriptions 1-2 sentences
789 
790### Option Design
791 
7921. **Meaningful labels**: Specific, clear names
7932. **Informative descriptions**: Explain what each option does
7943. **Show trade-offs**: Help user understand implications
7954. **Consistent detail**: All options equally explained
7965. **2-4 options**: Not too few, not too many
797 
798### Flow Design
799 
8001. **Logical order**: Questions flow naturally
8012. **Build on previous**: Later questions use earlier answers
8023. **Minimize questions**: Ask only what's needed
8034. **Group related**: Ask related questions together
8045. **Show progress**: Indicate where in flow
805 
806### User Experience
807 
8081. **Set expectations**: Tell user what to expect
8092. **Explain why**: Help user understand purpose
8103. **Provide defaults**: Suggest recommended options
8114. **Allow escape**: Let user cancel or restart
8125. **Confirm actions**: Summarize before executing
813 
814## Common Patterns
815 
816### Pattern: Feature Selection
817 
818```markdown
819Use AskUserQuestion:
820 
821Question: "Which features do you need?"
822Header: "Features"
823multiSelect: true
824Options:
825  - Authentication
826  - Authorization
827  - Rate Limiting
828  - Caching
829```
830 
831### Pattern: Environment Configuration
832 
833```markdown
834Use AskUserQuestion:
835 
836Question: "Which environment is this?"
837Header: "Environment"
838Options:
839  - Development (Local development)
840  - Staging (Pre-production testing)
841  - Production (Live environment)
842```
843 
844### Pattern: Priority Selection
845 
846```markdown
847Use AskUserQuestion:
848 
849Question: "What's the priority for this task?"
850Header: "Priority"
851Options:
852  - Critical (Must be done immediately)
853  - High (Important, do soon)
854  - Medium (Standard priority)
855  - Low (Nice to have)
856```
857 
858### Pattern: Scope Selection
859 
860```markdown
861Use AskUserQuestion:
862 
863Question: "What scope should we analyze?"
864Header: "Scope"
865Options:
866  - Current file (Just this file)
867  - Current directory (All files in directory)
868  - Entire project (Full codebase scan)
869```
870 
871## Combining Arguments and Questions
872 
873### Use Both Appropriately
874 
875**Arguments for known values:**
876```markdown
877---
878argument-hint: [project-name]
879allowed-tools: AskUserQuestion, Write
880---
881 
882Setup for project: $1
883 
884Now gather additional configuration...
885 
886Use AskUserQuestion for options that require explanation.
887```
888 
889**Questions for complex choices:**
890```markdown
891Project name from argument: $1
892 
893Now use AskUserQuestion to choose:
894- Architecture pattern
895- Technology stack
896- Deployment strategy
897 
898These require explanation, so questions work better than arguments.
899```
900 
901## Troubleshooting
902 
903**Questions not appearing:**
904- Verify AskUserQuestion in allowed-tools
905- Check question format is correct
906- Ensure options array has 2-4 items
907 
908**User can't make selection:**
909- Check option labels are clear
910- Verify descriptions are helpful
911- Consider if too many options
912- Ensure multiSelect setting is correct
913 
914**Flow feels confusing:**
915- Reduce number of questions
916- Group related questions
917- Add explanation between stages
918- Show progress through workflow
919 
920With AskUserQuestion, commands become interactive wizards that guide users through complex decisions while maintaining the clarity that simple arguments provide for straightforward inputs.
921