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

[PR #12676] feat: Add Guide Mode for beginner onboarding #14319

New Issue
Open
opened 2026-02-16 18:19:07 -05:00 by yindo · 0 comments
yindo commented 2026-02-16 18:19:07 -05:00
Owner
Copy Link
Copy Source

Original Pull Request: https://github.com/anomalyco/opencode/pull/12676

State: open
Merged: No

Summary

This PR introduces Guide Mode - a new agent mode designed to help beginners learn "vibe coding" (AI-assisted development).

Closes #12675

Problem

New developers transitioning to AI-assisted coding 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

Solution

Guide Mode provides a structured, educational onboarding experience through natural conversation.

How It Works

  1. Enter Guide Mode: opencode --agent guide
  2. Answer 5 Discovery Questions (natural conversation):
    • "What are you trying to build?"
    • "Who is this for?"
    • "What problem does this solve?"
    • "What's your experience level?"
    • "Any specific requirements?"
  3. Get Refined Specification - AI transforms vague ideas into detailed prompts
  4. Choose Next Step - Switch to Plan mode, Build mode, or continue refining

Changes

packages/opencode/src/agent/agent.ts:

  • Add 'guide' agent with conversational prompt and read-only permissions

packages/opencode/src/tool/guide.ts:

  • GuideEnterTool - Switch to guide mode
  • GuideExitTool - Exit guide mode to plan/build

packages/opencode/src/tool/registry.ts:

  • Register guide mode switching tools

packages/opencode/src/session/prompt.ts:

  • Guide mode initialization with greeting and system instructions

Benefits

For Users:

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

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

Testing

Guide Mode has been tested with various scenarios including:

  • Todo apps (beginner projects)
  • Portfolio websites (professional projects)
  • API integrations (intermediate projects)

The natural conversation flow works reliably across different use cases.

Example Usage

$ opencode --agent guide

AI: Hello! 👋 I'm excited to help you build something amazing!
    
    What are you trying to build?

User: I want a todo app

AI: Great idea! Who is this for?

... (continues through all 5 questions)

AI: [Creates refined specification]
    
    Would you like to:
    1) Switch to Plan mode
    2) Switch to Build mode
    3) Stay in Guide mode

I've opened issue #12675 describing this feature and am submitting this implementation for review. Happy to make any adjustments based on feedback!

**Original Pull Request:** https://github.com/anomalyco/opencode/pull/12676 **State:** open **Merged:** No --- ## Summary This PR introduces **Guide Mode** - a new agent mode designed to help beginners learn "vibe coding" (AI-assisted development). Closes #12675 ## Problem New developers transitioning to AI-assisted coding 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 ## Solution Guide Mode provides a structured, educational onboarding experience through natural conversation. ### How It Works 1. **Enter Guide Mode**: `opencode --agent guide` 2. **Answer 5 Discovery Questions** (natural conversation): - \"What are you trying to build?\" - \"Who is this for?\" - \"What problem does this solve?\" - \"What's your experience level?\" - \"Any specific requirements?\" 3. **Get Refined Specification** - AI transforms vague ideas into detailed prompts 4. **Choose Next Step** - Switch to Plan mode, Build mode, or continue refining ### Changes **packages/opencode/src/agent/agent.ts:** - Add 'guide' agent with conversational prompt and read-only permissions **packages/opencode/src/tool/guide.ts:** - GuideEnterTool - Switch to guide mode - GuideExitTool - Exit guide mode to plan/build **packages/opencode/src/tool/registry.ts:** - Register guide mode switching tools **packages/opencode/src/session/prompt.ts:** - Guide mode initialization with greeting and system instructions ## Benefits **For Users:** - ✅ Higher quality results from better prompts - ✅ Learn vibe coding principles naturally - ✅ Understand what information AI needs - ✅ Build confidence, avoid frustration **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 ## Testing Guide Mode has been tested with various scenarios including: - Todo apps (beginner projects) - Portfolio websites (professional projects) - API integrations (intermediate projects) The natural conversation flow works reliably across different use cases. ## Example Usage ```bash $ opencode --agent guide AI: Hello! 👋 I'm excited to help you build something amazing! What are you trying to build? User: I want a todo app AI: Great idea! Who is this for? ... (continues through all 5 questions) AI: [Creates refined specification] Would you like to: 1) Switch to Plan mode 2) Switch to Build mode 3) Stay in Guide mode ``` --- I've opened issue #12675 describing this feature and am submitting this implementation for review. Happy to make any adjustments based on feedback!
yindo added the pull-request label 2026-02-16 18:19:07 -05:00
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 pull-request
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#14319
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?