Development Roadmap: Iterative Learning

Philosophy

This roadmap prioritizes learning through doing over comprehensive upfront planning. We’ll build, dogfood, and iterate rather than designing everything in advance.

“We need to stub out the TUI to start getting benefits locally. Learn about wrong assumptions while dogfooding.”

Phase 1: Foundation & Research ✓ (Completed)

Status: Done
Goal: Understand the landscape and choose tools

What We Did

• Analyzed pi-mono architecture and features
• Evaluated Rust TUI ecosystem (ratatui + ratzilla)
• Mapped dependencies for feature parity
• Documented technology philosophy (Rust + WASM only)

Artifacts

• Documentation in /docs/ outlining architecture choices
• Dependency mapping (rust-dependencies-pi-parity.md)
• Clear stance: No TypeScript, no web frameworks

Decision: Ready to start building

Phase 2: Local TUI Prototype (Current)

Status: Starting now
Goal: Get a working TUI for local use, learn through dogfooding
Timeline: 2-4 weeks

The Plan

Don’t build everything at once. Build just enough to start using it daily.

Week 1: Hello TUI

┌─────────────────────────────────────┐
│  robit v0.0.1                 │
├─────────────────────────────────────┤
│                                     │
│  Welcome! Type a message below.     │
│                                     │
├─────────────────────────────────────┤
│  You: Hello, can you help me?       │
│  AI: Hi! I'd be happy to help.      │
│                                     │
│  > _                                │
│                                     │
└─────────────────────────────────────┘

Features:

• Basic ratatui app structure
• Simple input field
• Static response (mock LLM)
• Quit with ‘q’

Purpose: Learn ratatui basics, event loops, rendering

Week 2: Real LLM Integration

• Add reqwest for HTTP calls
• OpenAI integration (simple, no streaming)
• Config file for API key (simple TOML)
• Conversation history in memory

Purpose: Learn async in TUI context, config management

Week 3: Better UI

• Scrollable message view
• Multi-line input (TextArea widget)
• Conversation list sidebar
• Create/switch conversations

Purpose: Learn widgets, layout, state management

Week 4: Polish for Daily Use

• Markdown rendering (tui-markdown)
• Syntax highlighting in code blocks (syntect)
• Save conversations to disk (JSON or redb)
• Keyboard shortcuts (vim-style navigation)

Purpose: Make it actually usable for daily work

Success Criteria

• You use it for real work daily
• Clear understanding of what works/doesn’t
• List of “wrong assumptions” documented
• Clear pain points identified

Technical Approach

Start simple, no abstractions:

#![allow(unused)]
fn main() {
// main.rs - everything in one file initially
// Don't create crates/ workspace yet
// Don't worry about architecture
// Just make it work

mod app;      // App state
mod ui;       // Rendering
mod events;   // Input handling
mod llm;      // OpenAI client
}

Single crate, single binary:

[package]
name = "robit"
version = "0.0.1"

[[bin]]
name = "robit"
path = "src/main.rs"

[dependencies]
ratatui = "0.30"
crossterm = "0.29"
tokio = { version = "1", features = ["full"] }
reqwest = { version = "0.12", features = ["json"] }
serde = { version = "1.0", features = ["derive"] }
toml = "0.9"
# ... minimal deps

Don’t do yet:

• ❌ Separate crates/core/tui split
• ❌ WASM/web support
• ❌ Tool system
• ❌ Multiple LLM providers
• ❌ Tests (manual testing only)

Phase 3: Feature Parity with pi-mono

Status: Future
Goal: Match pi-mono’s core features
Timeline: 4-8 weeks (after Phase 2 feels good)

When to Start

Start this phase when:

• You’re using the Phase 2 TUI daily
• No major architecture regrets
• Clear understanding of needed features

Features to Implement

Based on pi-mono analysis:

Core Chat

• Streaming responses (real-time token display)
• Multi-model support (OpenAI, Anthropic, etc.)
• Model switching mid-conversation
• Token usage tracking

Editor

• Vim-style text editor for input
• Syntax highlighting while typing
• Multi-line editing with proper indentation
• Clipboard integration (arboard)

History & Sessions

• Session tree navigation (like pi’s tree selector)
• Named conversations
• Search through history
• Export conversations

Display

• Better markdown rendering
• Code block with syntax highlighting
• Diff viewer for code changes
• File tree sidebar (tui-tree-widget)

Config

• Theme system
• Keybinding configuration
• Profile support (different API keys, defaults)

Architecture Evolution

Split into crates when needed:

robit/                    # Single repo
├── Cargo.toml                  # Workspace
├── crates/
│   ├── robit-core/           # Extract when needed
│   │   ├── src/
│   │   │   ├── lib.rs
│   │   │   ├── conversation.rs
│   │   │   ├── llm/
│   │   │   └── config.rs
│   │   └── Cargo.toml
│   │
│   └── robit-tui/            # Main TUI app
│       ├── src/
│       │   ├── main.rs
│       │   ├── app.rs
│       │   ├── ui/
│       │   └── widgets/
│       └── Cargo.toml
│
└── docs/

Not yet:

• ❌ WebAssembly build
• ❌ Separate web UI
• ❌ Tool/agent system

Phase 4: Package Architecture

Status: Future
Goal: Structure like pi-mono but for our needs
Timeline: After Phase 3 stable

Planning

Design package structure based on learnings:

crates/
├── robit-core/               # Reusable core
├── robit-tui/                # Terminal app
├── robit-cli/                # Non-interactive CLI
├── robit-web/                # WASM build (maybe)
└── robit-lsp/                # Future: LSP integration?

Key decisions to make:

• What goes in core vs TUI-specific?
• Async runtime abstraction for WASM?
• Plugin system design?

Guiding principle: Split when it hurts not to, not before.

Phase 5: Agent Features

Status: Future
Goal: Add agentic capabilities
Timeline: After Phase 4

Core Capabilities

Advanced agent functionality includes:

• Tool calling (bash, file operations)
• Autonomous agent mode
• GitHub integration (PRs, issues)
• Search capabilities
• Multi-file editing

Approach

Don’t replicate everything:

• Pick features that fit your workflow
• Start with bash tool only
• Add file operations
• Then GitHub integration
• Then search

Security first:

• Sandboxed execution (wasmtime for tools)
• User confirmation for destructive ops
• Audit logging

Phase 6: Mobile/Remote Access (MVP)

Status: Future
Goal: Prompt from phone, agent makes PRs
Timeline: After agent features work

The MVP Definition

“Once I can prompt from my phone and my agent can make PRs and do searches, this feels like a proper MVP to harden.”

Simplest path first:

Option 1: SSH (Easiest)

Phone → SSH app → Terminal → robit

• Ensure TUI works over SSH
• Maybe optimize for mobile terminal size
• Test with Blink Shell (iOS) or Termux (Android)

Pros: Zero additional code
Cons: Requires SSH access, terminal UI on small screen

Option 2: Chat Integration

Phone → Telegram/Discord bot → robit agent

• Simple bot that forwards messages
• Agent runs on server
• Responses sent back to chat

Pros: Native mobile experience
Cons: Requires bot hosting, async conversation style

Option 3: Web Server (More Work)

Phone → Browser → robit-server → agent

• REST API wrapper around agent
• Simple web UI or reuse WASM
• Authentication

Pros: Full control
Cons: Most complex, security considerations

Recommendation

Start with Option 1 (SSH):

• Free, immediate
• See if you actually need mobile access
• Learn what mobile UX should be

Then Option 2 (Chat):

• If SSH is too clunky
• Telegram bot is ~100 lines of code
• Good enough for MVP

Save Option 3 (Web):

• Only if chat isn’t sufficient
• For after “proper MVP” is hardened

Decision Gates

Don’t advance to next phase until:

Phase 1 → 2

• Documentation complete
• Clear on Rust + WASM philosophy
• Ready to write code

Phase 2 → 3

• Daily dogfooding for 2+ weeks
• Documented “wrong assumptions”
• Clear on what features are needed
• TUI feels “good enough” to invest more

Phase 3 → 4

• Feature parity with pi-mono
• Stable daily use
• Pain points from monolithic codebase
• Clear need for package split

Phase 4 → 5

• Clean package architecture
• Core library published (internal)
• Ready for agent features

Phase 5 → 6

• Agent makes PRs successfully
• Agent searches code
• Ready for mobile access

Current Focus

Right now: Phase 2 - Local TUI Prototype

This week:

1. Create single-file ratatui app
2. Basic input/output loop
3. Mock LLM responses
4. Run it, use it, break it

Not doing yet:

• ❌ Planning Phase 3-6 in detail
• ❌ Over-engineering architecture
• ❌ WebAssembly builds
• ❌ Package splits

Learning goals:

• How does ratatui feel in practice?
• What’s annoying about the API?
• What do we actually need vs what we think we need?
• Wrong assumptions to document

Notes

Dogfooding Guidelines

While using Phase 2 prototype:

1. Keep a “pain log” - What’s annoying? What’s broken?
2. Note missing features - Don’t implement, just document
3. Track assumptions - “I thought X would work but Y happens”
4. Daily commits - Even if messy, commit your working state

When to Course Correct

If during Phase 2 you discover:

• ratatui doesn’t fit → Pivot to different TUI lib
• WASM is wrong approach → Revisit philosophy
• TUI is insufficient → Maybe web-first makes sense
• Rust is wrong choice → Better to know early

Don’t be afraid to throw away Phase 2 code. It’s for learning.

Summary

Current mantra: Build the smallest thing that teaches us the most.