[FEATURE]: Guide Mode - Interactive Onboarding for New Developers

[doozie-akshay]

Feature Request: Guide Mode

Problem Statement

New developers transitioning to "vibe coding" (AI-assisted development) struggle with:

• Vague prompts: "Make a website" leads to poor results
• Unclear expectations: Don't know what to ask AI for
• Knowledge gaps: Unfamiliar with technical terminology
• Frustration: First-time failures lead to abandonment

Current plan/build modes assume users already know what they want to build.

Proposed Solution: Guide Mode

An interactive onboarding mode that acts as a coding mentor for beginners. Instead of jumping straight into coding, Guide Mode asks discovery questions, refines vague ideas, and teaches best practices.

How It Works

Phase 1: Discovery (NEW)
Structured questionnaire to understand the project:

1. "What are you trying to build?" - Understand the goal
2. "Who is this for?" - Personal vs public affects tech choices
3. "What problem does it solve?" - Forces value proposition thinking
4. "What's your experience level?" - Beginner/Intermediate/Advanced
5. "Any specific requirements?" - Tech preferences, constraints

Phase 2: Prompt Refinement (NEW)
Transforms vague input into structured specification:

Before: "Make me a website"
After: "Create a responsive portfolio website for a junior developer showcasing 3 projects. Use React with TypeScript, Tailwind CSS for styling. Include: hero section, projects grid with GitHub links, contact form. Target: beginner-friendly code with comments."

Phase 3: Guided Research & Build

• Explains each step as it happens
• Provides educational context
• Validates understanding with checkpoints
• Suggests alternatives with explanations

Architecture

New Components:

• src/hooks/useGuideMode.ts - Guide workflow orchestration
• src/components/GuideMode/DiscoveryForm.tsx - Questionnaire UI
• src/components/GuideMode/GuideProgress.tsx - Educational progress tracker
• Add "guide" to system_prompts.json agent roles
• Add "guide" mode to .kilocodemodes

Modified:

• src/hooks/useAgentWorkflow.ts - Add guide phase
• src/lib/store/useStore.ts - Add guide state
• src/components/IDE.tsx - Guide mode UI integration

Key Features

1. Smart Question Branching - Adapt questions based on answers
2. Template Suggestions - "Sounds like you want a CRUD app..."
3. Prompt Quality Score - Show before/after, teach what improved
4. Progressive Disclosure - More hand-holding for beginners
5. Post-Build Education - Explain key parts after generation

Benefits

For Users:

• ✅ Higher quality results from better prompts
• ✅ Learn vibe coding principles
• ✅ Understand WHY decisions are made
• ✅ Build confidence, avoid frustration

For Kilo CLI:

• ✅ Higher user satisfaction and retention
• ✅ Reduced "AI didn't understand me" complaints
• ✅ Educational value = word of mouth
• ✅ Differentiator from other AI coding tools

Acceptance Criteria

• Guide Mode appears in mode selector
• Discovery questionnaire collects 5 key data points
• Vague prompts transformed into structured specifications
• Educational explanations at each step
• Experience level affects code complexity
• Works with all existing providers (OpenAI, Ollama, etc.)
• Can switch from Guide to Plan/Build mid-session
• Documentation for users

Success Metrics

• Time to first successful build (decrease)
• User retention after first session (increase)
• Support requests about misunderstood prompts (decrease)

Implementation Phases

Phase 1 (MVP):

• Basic discovery questions
• Simple prompt refinement
• Integration with existing research/build phases

Phase 2 (Enhancement):

• Smart branching
• Template suggestions
• Prompt quality scoring
• Post-build education

Phase 3 (Advanced):

• Community prompt sharing
• Progressive learning paths
• Skill assessment and recommendations

---

This feature could be a major differentiator for Kilo CLI - no other AI coding tool has a true "beginner mode" that teaches users HOW to work with AI effectively!