OpenQode/Documentation/GOOSE_ULTRA_V2_IMPLEMENTATION_PLAN.md

Goose Ultra V2 - Core Implementation Plan

Mission: Perfect the chat-to-code experience by building on the original Goose concept with world-class IDE integration and AI-native patterns.

---

Phase 1: Core State Machine & Flow (Week 1)

1.1 State Machine Architecture

Implement the primary flow: NoProject → IdeaCapture → Planning → Building → PreviewReady

Key States:

• NoProject: Landing screen, awaiting user idea
• IdeaCapture: User describes their vision in natural language
• Planning: AI generates implementation blueprint with file structure
• Building: Code generation in progress with streaming feedback
• PreviewReady: Live preview + Monaco Editor available
• Editing: User actively modifying code in Monaco

State Transitions:

type StateTransition = {
  from: OrchestratorState;
  to: OrchestratorState;
  trigger: 'user_input' | 'ai_complete' | 'build_complete' | 'user_edit';
  validator?: (context: Context) => boolean;
};

1.2 Orchestrator Pattern (from Goose)

Source: https://github.com/block/goose

Learnings to integrate:

1. Agent Loop: Goose uses a continuous agent loop with tool calling
2. Session Management: Persistent sessions with message history
3. Tool Integration: Structured tool calling pattern for file operations
4. Error Recovery: Graceful fallback when tools fail

Implementation:

// orchestrator-v2.ts
export class GooseUltraOrchestrator {
  private state: OrchestratorState;
  private session: Session;
  private aiProvider: QwenProvider;
  
  async processUserIntent(input: string) {
    // 1. Validate current state allows this transition
    // 2. Send to AI with state context
    // 3. Stream response with state updates
    // 4. Transition to next state on completion
  }
  
  async executeStateTransition(transition: StateTransition) {
    // Atomic state updates with rollback capability
  }
}

---

Phase 2: IDE Core - Monaco Integration (Week 1-2)

2.1 Monaco Editor Setup

Source: https://github.com/microsoft/vscode

Core Features to Implement:

1. Syntax Highlighting: Language-aware highlighting for HTML/CSS/JS
2. IntelliSense: Auto-completion based on file context
3. Multi-File Support: Tabbed interface for index.html, style.css, script.js
4. Live Error Detection: Real-time linting and validation
5. Diff View: Show AI-generated changes vs. current code

Implementation:

// components/MonacoEditor.tsx
import * as monaco from 'monaco-editor';

export const CodeEditor = () => {
  const [files, setFiles] = useState<Record<string, string>>({});
  const [activeFile, setActiveFile] = useState<string>('index.html');
  
  useEffect(() => {
    const editor = monaco.editor.create(editorRef.current, {
      value: files[activeFile],
      language: getLanguage(activeFile),
      theme: 'goose-ultra-dark',
      minimap: { enabled: true },
      fontSize: 14,
      fontFamily: 'JetBrains Mono',
      lineNumbers: 'on',
      contextmenu: true,
      automaticLayout: true,
    });
    
    // Listen for changes and update state
    editor.onDidChangeModelContent(() => {
      setFiles({ ...files, [activeFile]: editor.getValue() });
    });
  }, [activeFile]);
  
  return (
    <div className="editor-container">
      <FileTabs files={Object.keys(files)} active={activeFile} onChange={setActiveFile} />
      <div ref={editorRef} className="monaco-editor" />
    </div>
  );
};

2.2 Custom Monaco Theme

monaco.editor.defineTheme('goose-ultra-dark', {
  base: 'vs-dark',
  inherit: true,
  rules: [
    { token: 'comment', foreground: '6A9955', fontStyle: 'italic' },
    { token: 'keyword', foreground: 'C586C0' },
    { token: 'string', foreground: 'CE9178' },
    { token: 'number', foreground: 'B5CEA8' },
  ],
  colors: {
    'editor.background': '#0A0A0B',
    'editor.foreground': '#D4D4D4',
    'editor.lineHighlightBackground': '#ffffff0a',
    'editorCursor.foreground': '#34D399',
  }
});

---

Phase 3: Qwen OAuth Integration (Week 2)

3.1 OAuth Flow Implementation

Critical Dependency - De-risk this first

Flow:

1. User clicks "Authenticate with Qwen"
2. Open browser to Qwen OAuth page
3. User grants permission
4. Redirect to local server with auth code
5. Exchange code for access token + refresh token
6. Store tokens securely (encrypted)

Implementation:

// services/qwen-oauth.ts
export class QwenOAuthService {
  private clientId = process.env.QWEN_CLIENT_ID;
  private redirectUri = 'http://localhost:8765/callback';
  
  async startOAuthFlow() {
    const state = generateRandomState();
    const authUrl = `https://dashscope.aliyuncs.com/oauth/authorize?` +
      `client_id=${this.clientId}&` +
      `redirect_uri=${encodeURIComponent(this.redirectUri)}&` +
      `response_type=code&` +
      `state=${state}`;
    
    // Open browser
    shell.openExternal(authUrl);
    
    // Start local server to receive callback
    const server = await this.createCallbackServer();
    
    return new Promise((resolve) => {
      server.on('auth_complete', (tokens) => {
        this.storeTokens(tokens);
        resolve(tokens);
      });
    });
  }
  
  async refreshAccessToken(refreshToken: string) {
    // Token refresh logic
  }
  
  private async storeTokens(tokens: TokenSet) {
    // Encrypt and store in OS keychain
    const encrypted = encryptTokens(tokens);
    await keytar.setPassword('goose-ultra', 'qwen-tokens', encrypted);
  }
}

3.2 Qwen API Client

// services/qwen-client.ts
export class QwenClient {
  private accessToken: string;
  
  async chat(messages: Message[], options: ChatOptions) {
    const response = await fetch('https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'qwen-coder-plus',
        input: { messages },
        parameters: {
          stream: true,
          temperature: 0.7,
        }
      })
    });
    
    // Handle streaming response
    const reader = response.body.getReader();
    for await (const chunk of this.readStream(reader)) {
      options.onChunk?.(chunk);
    }
  }
}

---

Phase 4: AI-Native Patterns (Week 2-3)

4.1 CodeNomad Learnings

Source: https://github.com/NeuralNomadsAI/CodeNomad.git

Patterns to Adopt:

1. Context-Aware Prompting: Include file structure, dependencies, and user preferences in AI context
2. Streaming with Artifacts: Display partial results as they generate
3. Multi-Step Planning: Break complex requests into atomic steps
4. Code Validation: Automatic syntax checking + security scanning before applying changes
5. Rollback Mechanism: Git-like history for AI-generated changes

4.2 Enhanced AI Prompt Engineering

// services/prompt-builder.ts
export class PromptBuilder {
  buildCodeGenerationPrompt(context: CodeContext) {
    return `
<role>You are an expert full-stack developer</role>

<context>
  <project_type>${context.projectType}</project_type>
  <file_structure>
    ${context.files.map(f => `- ${f.name}`).join('\n    ')}
  </file_structure>
  <user_preferences>
    - UI Library: ${context.uiLibrary || 'Vanilla CSS'}
    - Style: ${context.styleGuide || 'Modern, minimal'}
  </user_preferences>
</context>

<task>
  ${context.userRequest}
</task>

<constraints>
  1. CRITICAL: Output ONLY executable code - no explanations
  2. Use single-file HTML with embedded CSS and JS
  3. Include actual UI elements (buttons, inputs, forms)
  4. No server-side templates or frameworks
  5. Start immediately with: <!DOCTYPE html>
</constraints>

<output_format>
<!DOCTYPE html>
<html>
  <!-- Your implementation here -->
</html>
</output_format>
    `;
  }
}

4.3 Code Validation Pipeline

// services/code-validator.ts
export class CodeValidator {
  async validate(code: string): Promise<ValidationResult> {
    const results = await Promise.all([
      this.checkSyntax(code),
      this.checkSecurity(code),
      this.checkAccessibility(code),
      this.checkPerformance(code),
    ]);
    
    return {
      isValid: results.every(r => r.passed),
      errors: results.flatMap(r => r.errors),
      warnings: results.flatMap(r => r.warnings),
    };
  }
  
  private async checkSecurity(code: string) {
    // Scan for XSS, eval(), dangerouslySetInnerHTML, etc.
    const dangerousPatterns = [
      /eval\(/g,
      /innerHTML\s*=/g,
      /document\.write/g,
    ];
    
    const violations = [];
    for (const pattern of dangerousPatterns) {
      if (pattern.test(code)) {
        violations.push({
          severity: 'high',
          message: `Detected potentially unsafe pattern: ${pattern}`,
        });
      }
    }
    
    return { passed: violations.length === 0, errors: violations };
  }
}

---

Phase 5: Vibe Style Guide (Week 3)

5.1 AI Personality

Tone: Confident, efficient, slightly playful Voice: Direct but encouraging Behavior: Proactive suggestions, anticipates needs

Examples:

• ❌ "Here's the code you requested."
• ✅ "Built. Preview ready. I also added responsive breakpoints—mobile looks slick."

5.2 UI Motion

Principles:

1. Purposeful: Every animation conveys state or provides feedback
2. Swift: 200-300ms for most transitions
3. Natural: Easing curves mimic physical motion

Key Animations:

/* State Transitions */
.state-enter {
  animation: slideAndFade 300ms cubic-bezier(0.16, 1, 0.3, 1);
}

@keyframes slideAndFade {
  from {
    opacity: 0;
    transform: translateY(10px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

/* AI Thinking Indicator */
.ai-thinking {
  animation: pulse 1.5s ease-in-out infinite;
}

/* Code Appearing */
.code-stream {
  animation: typewriter 0.5s steps(40, end);
}

5.3 Sound Design

Audio Cues:

• start-build.mp3: Satisfying "whoosh" when AI begins work
• build-complete.mp3: Subtle "ding" on completion
• error.mp3: Gentle "thud" for errors (not harsh)
• keystroke.mp3: Optional typing sounds for AI streaming

Implementation:

// services/sound-manager.ts
export class SoundManager {
  private sounds = new Map<string, HTMLAudioElement>();
  
  constructor() {
    this.preload(['start-build', 'build-complete', 'error', 'keystroke']);
  }
  
  play(sound: SoundType, volume = 0.3) {
    const audio = this.sounds.get(sound);
    if (audio && !this.isMuted) {
      audio.volume = volume;
      audio.currentTime = 0;
      audio.play();
    }
  }
}

---

Implementation Roadmap

Week 1: Foundation

• Set up Next.js project structure
• Implement core state machine
• Integrate Monaco Editor basic setup
• Create Orchestrator V2 with state management

Week 2: AI Integration

• Implement Qwen OAuth flow (PRIORITY)
• Build Qwen API client with streaming
• Create prompt builder with context injection
• Add code validation pipeline

Week 3: Polish & Patterns

• Implement CodeNomad patterns
• Create vibe style guide document
• Add sound design
• Build diff viewer for AI changes

---

Architecture Diagram

┌─────────────────────────────────────────────────┐
│                  User Interface                 │
├─────────────────────────────────────────────────┤
│  StartView  →  ChatPanel  →  MonacoEditor      │
│                     ↓                            │
│              PreviewPanel                        │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│            Orchestrator V2 (State Machine)      │
├─────────────────────────────────────────────────┤
│  - State Management                             │
│  - Transition Validation                        │
│  - Tool Coordination                            │
└─────────────────────────────────────────────────┘
                      ↓
┌──────────────┬──────────────┬──────────────────┐
│ Qwen Client  │  Monaco API  │  File System     │
│ (OAuth)      │  (VSCode)    │  (Electron)      │
└──────────────┴──────────────┴──────────────────┘

---

Success Metrics

1. Time to First Code: < 5 seconds from user idea to AI response
2. Code Quality: 95%+ of generated code passes validation
3. User Flow: Users can go from idea → working preview in under 60 seconds
4. OAuth Reliability: 100% success rate on token refresh
5. Editor Performance: Monaco remains responsive with files up to 10,000 lines

---

Next Steps

1. Review and approve this plan
2. Set up new Next.js project structure
3. Begin Week 1 implementation
4. Daily check-ins on progress

Would you like me to start implementing Phase 1 now?