anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-22 02:05:26 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

[Feature Request]: Guide Mode - Interactive Onboarding for New Developers #8824

New Issue
Open
opened 2026-02-16 18:10:56 -05:00 by yindo · 1 comment
yindo commented 2026-02-16 18:10:56 -05:00
Owner
Copy Link
Copy Source

Originally created by @doozie-akshay on GitHub (Feb 8, 2026).

Originally assigned to: @thdxr on GitHub.

Feature Request: Guide Mode

Problem Statement

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

  • Vague prompts: "Make a website" leads to poor, generic results
  • Unclear expectations: Don't know what information AI needs to help effectively
  • Knowledge gaps: Unfamiliar with technical terminology and best practices
  • Frustration: First-time failures lead to abandonment of AI coding tools

Currently, opencode (like most AI coding tools) assumes users already know how to communicate requirements effectively.

Proposed Solution: Guide Mode

A new primary agent mode that acts as an interactive mentor for beginners. Instead of jumping straight into coding, Guide Mode asks discovery questions, refines vague ideas, and teaches users HOW to work with AI effectively.

How It Works

Phase 1: Discovery (Natural Conversation)
Guide Mode asks 5 key questions in conversational format:

  1. "What are you trying to build? Describe your idea in your own words."
  2. "Who is this for? (Just me, Friends/Family, Public users, or Business?)"
  3. "What problem does this solve? Why do you need it?"
  4. "What's your experience level with coding? (Beginner/Intermediate/Advanced)"
  5. "Any specific requirements? (Tech preferences, constraints, must-haves)"

Phase 2: Refinement
Transforms the conversation into a structured, actionable 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 with intro, projects grid with GitHub links, contact form. Target: beginner-friendly code with comments explaining key concepts."

Phase 3: Transition
After discovery, offers to switch to:

  • Plan mode (create detailed implementation plan)
  • Build mode (start coding immediately)
  • Continue in Guide mode (further refinement)

Implementation Approach

Based on opencode architecture, Guide Mode would be implemented as:

  1. New Agent Definition (src/agent/agent.ts)

    • Add "guide" as a native primary agent
    • Read-only permissions (no edit/write/bash)
    • Custom prompt for conversational discovery

  2. Mode Switching Tools (src/tool/guide.ts)

    • guide_enter - Switch from build/plan to guide mode
    • guide_exit - Switch from guide to build/plan mode

  3. Prompt Injection (src/session/prompt.ts)

    • Inject guide mode instructions when agent changes to guide
    • Similar to how plan mode injects PROMPT_PLAN

  4. Tool Registration (src/tool/registry.ts)

    • Register guide mode switching tools

Benefits

For Users:

  • ✅ Higher quality results from better prompts
  • ✅ Learn vibe coding principles naturally
  • ✅ Understand what information AI needs
  • ✅ Build confidence, avoid frustration
  • ✅ No prompt engineering knowledge required

For OpenCode:

  • ✅ Higher user satisfaction and retention
  • ✅ Reduced "AI didn't understand me" complaints
  • ✅ Educational value = word of mouth
  • ✅ Differentiator from other AI coding tools
  • ✅ True onboarding that teaches users HOW to work with AI

Success Metrics

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

Acceptance Criteria

  • Guide agent defined with appropriate permissions (read-only)
  • 5 discovery questions asked in natural conversation
  • User answers transformed into structured specification
  • Mode switching between guide/build/plan works seamlessly
  • Works with all supported providers

Related Work

This feature has been implemented and tested in a fork (Kilo CLI) with positive results. I'm willing to contribute this back to opencode upstream.

Additional Context

This addresses a gap in the AI coding tool ecosystem - while many tools help experienced developers code faster, few teach beginners HOW to work with AI effectively. Guide Mode bridges this gap by providing structured onboarding that improves user skills over time.

I'm willing to implement this feature and submit a PR. Please let me know if this aligns with the project roadmap and if you'd like me to proceed with the implementation.

Originally created by @doozie-akshay on GitHub (Feb 8, 2026). Originally assigned to: @thdxr on GitHub. ## Feature Request: Guide Mode ### Problem Statement New developers transitioning to AI-assisted coding ("vibe coding") struggle with: - **Vague prompts**: \"Make a website\" leads to poor, generic results - **Unclear expectations**: Don't know what information AI needs to help effectively - **Knowledge gaps**: Unfamiliar with technical terminology and best practices - **Frustration**: First-time failures lead to abandonment of AI coding tools Currently, opencode (like most AI coding tools) assumes users already know how to communicate requirements effectively. ### Proposed Solution: Guide Mode A new primary agent mode that acts as an interactive mentor for beginners. Instead of jumping straight into coding, Guide Mode asks discovery questions, refines vague ideas, and teaches users HOW to work with AI effectively. ### How It Works **Phase 1: Discovery** (Natural Conversation) Guide Mode asks 5 key questions in conversational format: 1. \"What are you trying to build? Describe your idea in your own words.\" 2. \"Who is this for? (Just me, Friends/Family, Public users, or Business?)\" 3. \"What problem does this solve? Why do you need it?\" 4. \"What's your experience level with coding? (Beginner/Intermediate/Advanced)\" 5. \"Any specific requirements? (Tech preferences, constraints, must-haves)\" **Phase 2: Refinement** Transforms the conversation into a structured, actionable 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 with intro, projects grid with GitHub links, contact form. Target: beginner-friendly code with comments explaining key concepts.\" **Phase 3: Transition** After discovery, offers to switch to: - Plan mode (create detailed implementation plan) - Build mode (start coding immediately) - Continue in Guide mode (further refinement) ### Implementation Approach Based on opencode architecture, Guide Mode would be implemented as: 1. **New Agent Definition** (`src/agent/agent.ts`) - Add \"guide\" as a native primary agent - Read-only permissions (no edit/write/bash) - Custom prompt for conversational discovery 2. **Mode Switching Tools** (`src/tool/guide.ts`) - `guide_enter` - Switch from build/plan to guide mode - `guide_exit` - Switch from guide to build/plan mode 3. **Prompt Injection** (`src/session/prompt.ts`) - Inject guide mode instructions when agent changes to guide - Similar to how plan mode injects PROMPT_PLAN 4. **Tool Registration** (`src/tool/registry.ts`) - Register guide mode switching tools ### Benefits **For Users:** - ✅ Higher quality results from better prompts - ✅ Learn vibe coding principles naturally - ✅ Understand what information AI needs - ✅ Build confidence, avoid frustration - ✅ No prompt engineering knowledge required **For OpenCode:** - ✅ Higher user satisfaction and retention - ✅ Reduced \"AI didn't understand me\" complaints - ✅ Educational value = word of mouth - ✅ Differentiator from other AI coding tools - ✅ True onboarding that teaches users HOW to work with AI ### Success Metrics - Time to first successful project (decrease) - User retention after first session (increase) - Support requests about misunderstood prompts (decrease) ### Acceptance Criteria - [ ] Guide agent defined with appropriate permissions (read-only) - [ ] 5 discovery questions asked in natural conversation - [ ] User answers transformed into structured specification - [ ] Mode switching between guide/build/plan works seamlessly - [ ] Works with all supported providers ### Related Work This feature has been implemented and tested in a fork (Kilo CLI) with positive results. I'm willing to contribute this back to opencode upstream. ### Additional Context This addresses a gap in the AI coding tool ecosystem - while many tools help experienced developers code faster, few teach beginners HOW to work with AI effectively. Guide Mode bridges this gap by providing structured onboarding that improves user skills over time. --- **I'm willing to implement this feature and submit a PR.** Please let me know if this aligns with the project roadmap and if you'd like me to proceed with the implementation.
yindo commented 2026-02-16 18:10:57 -05:00
Author
Owner
Copy Link
Copy Source

@github-actions[bot] commented on GitHub (Feb 8, 2026):

This issue might be a duplicate or related to existing issues. Please check:

  • #3662: Request for a comprehensive setup guide for OpenCode (similar onboarding/education goal)
  • #7219: Kiosk mode for simplified web UI (related to simplified onboarding experiences)
  • #12498: Config-driven agent system (relevant to the proposed agent architecture for Guide Mode)
  • #8804: Use agent description as prompt placeholder text (related to contextual guidance for users)

While these aren't exact duplicates, they address overlapping concerns about user onboarding, guidance, and agent system architecture. Feel free to ignore if your Guide Mode feature addresses these differently.

@github-actions[bot] commented on GitHub (Feb 8, 2026): This issue might be a duplicate or related to existing issues. Please check: - #3662: Request for a comprehensive setup guide for OpenCode (similar onboarding/education goal) - #7219: Kiosk mode for simplified web UI (related to simplified onboarding experiences) - #12498: Config-driven agent system (relevant to the proposed agent architecture for Guide Mode) - #8804: Use agent description as prompt placeholder text (related to contextual guidance for users) While these aren't exact duplicates, they address overlapping concerns about user onboarding, guidance, and agent system architecture. Feel free to ignore if your Guide Mode feature addresses these differently.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#8824
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?