opencode/docs/ROADMAP.md

Agent-Core Roadmap

Current State

Agent-core is a fork of OpenCode with three personas (Zee, Stanley, Johny) sharing orchestration and memory layers.

What Works

• Provider system with Antigravity, Cerebras, OpenRouter
• Three personas with Tab switching
• Config symlinks for global access
• OAuth auth for Anthropic and Google
• Built-in antigravity models (Claude, Gemini)

---

Phase 1: Foundation (Current)

1.1 Provider Stability

• Fix Antigravity model registration (use built-in antigravity-* models)
• Disable redundant Vertex providers
• Document provider setup (docs/PROVIDERS.md)
• Auto-refresh OAuth tokens before expiry (not just on-demand)
• Add provider health checks in TUI

1.2 Config Management

• Symlink global config to project config
• Single source of truth for agent definitions (remove duplication)
  • Agent files (.agent-core/agent/*.md) have concise config + identity
  • Skill files (.claude/skills/*/SKILL.md) have detailed capabilities
  • Agent files reference skills via skill: frontmatter field
• Config validation on startup (already implemented via zod schemas + FormatError)
• Migration tool for config schema changes (agent-core debug migrate)

---

Phase 2: Personas

2.1 Zee (Personal Assistant) - COMPLETE

• Qdrant memory integration
  • Store conversation summaries (zee:memory-store tool wired to Qdrant)
  • Semantic search across memories (zee:memory-search tool wired)
  • MemoryStore service created (src/memory/store.ts)
  • Local BGE-M3 embeddings (1024d) via vLLM instead of OpenAI
  • Fixed Qdrant collection selection bug (currentCollection)
  • Key facts extraction (src/personas/fact-extractor.ts)
    • Heuristic + LLM extraction options
    • Automatic categorization (personal, preference, decision, technical)
    • Session lifecycle hook for auto-extraction
• Messaging integration
  • WhatsApp via whatsapp-web.js (src/gateway/whatsapp.ts)
  • Telegram gateway (src/gateway/telegram.ts)
  • zee:messaging tool wired to daemon endpoints
  • zee:whatsapp-react tool for message reactions
  • Proactive messaging (send without prior message)
  • Multi-persona Telegram (Stanley/Johny bots via Zee's account)
  • Discord integration removed (not needed)
• Calendar integration
  • Google Calendar sync (zee:calendar tool working)
  • Smart scheduling
    • Event creation/update/delete via Google Calendar API
    • Find free time slots with business hours awareness
    • Meeting time suggestions with scoring (prefer morning/afternoon)
    • Natural language quick-add via Google's NLP
    • Conflict detection

2.2 Stanley (Investing) - COMPLETE

• OpenBB integration for market data
  • CLI bridge created (stanley_cli.py → tools.ts)
  • 5 domain tools: market-data, portfolio, sec-filings, research, nautilus
  • FIXED: OpenBB version mismatch → yfinance fallback implemented
  • OpenBBAdapter auto-detects OpenBB issues and uses direct yfinance
• Portfolio tracking
  • Position management (~/.zee/stanley/portfolio.json)
  • Holdings status via portfolio status command
  • P&L tracking with live price fallback
  • Risk metrics (VaR, Sharpe, Sortino)
• SEC filings analysis
  • EdgarAdapter created (stanley/accounting/edgar_adapter.py)
  • FIXED: pyarrow compatibility → convert to list before slicing
  • 10-K, 10-Q, 8-K, 13F filings working
• NautilusTrader backtesting integration
  • Strategy-info command works
  • Backtest command works with yfinance data
  • Built-in strategies: momentum (EMA cross), mean-reversion (SMA threshold)
  • FIXED: Indicator import path for nautilus_trader 1.200+

Files modified in Stanley Python repo:

• stanley/accounting/edgar_adapter.py - pyarrow compatibility fix
• stanley/data/providers/openbb_provider.py - yfinance fallback
• stanley/integrations/nautilus/indicators/*.py - import fix
• requirements-lock.txt - created with pinned versions

2.3 Johny (Learning) - COMPLETE

• Knowledge graph implementation
  • Topic DAG with prerequisites (johny/knowledge/graph.py)
  • Learning path generation (topological sort)
  • Mastery level tracking (6 levels: Unknown → Fluent)
• Spaced repetition (MathAcademy-inspired)
  • Ebbinghaus decay modeling (R = e^(-t/S))
  • FIRe (Fractional Implicit Repetition) for prerequisite review credit
  • Priority-based review queue
• Study session management
  • Session lifecycle (start, pause, resume, end)
  • Time tracking with pause support
• CLI bridge (scripts/johny_cli.py)
  • JSON stdio output for agent-core integration
  • 5 domain tools: study, knowledge, mastery, review, practice

Files created in Johny Python repo:

• johny/knowledge/ - DAG, topics, learning paths
• johny/mastery/ - levels, tracker, retention calculation
• johny/review/ - scheduler, Ebbinghaus curves
• johny/practice/ - session management
• scripts/johny_cli.py - CLI bridge

Files created in agent-core:

• src/domain/johny/tools.ts - TypeScript domain tools

---

Phase 3: Shared Infrastructure

3.1 Memory System - COMPLETE

• Qdrant vector storage setup (src/memory/qdrant.ts, store.ts)
  • QdrantVectorStorage with full CRUD operations
  • MemoryStore high-level API for save/search/list
  • Collection management with auto-creation
• Embedding generation (src/memory/embedding.ts)
  • Qwen3-Embedding-8B via Nebius API (4096d, #1 on MTEB)
  • Voyage AI provider support
  • OpenAI/local fallback options
• Conversation continuity across compactions (src/personas/continuity.ts)
  • ContinuityManager with session lifecycle
  • Key fact extraction (heuristic + LLM ready)
  • Summary generation
  • Context restoration from previous sessions
• Cross-persona memory sharing
  • Namespace-based isolation
  • Shared Qdrant collections
  • Memory bridge for persona state (src/personas/memory-bridge.ts)
• Memory search MCP tool (personas-memory server)

3.2 Orchestration (Tiara) - COMPLETE

• Drone spawning via Task tool (src/personas/tiara.ts)
  • Orchestrator class with full worker lifecycle
  • Task submission and assignment
  • Worker status tracking (spawning, working, idle, terminated)
• WezTerm pane management (src/personas/wezterm.ts)
  • WeztermPaneBridge for pane creation/management
  • Layout setup (horizontal/vertical/grid)
  • Status pane updates
• SPARC methodology integration (vendor/tiara/)
  • Tiara submodule with claude-flow
• Background task status tracking
  • DroneWaiter for async completion notifications
  • Event subscription system
  • State persistence to Qdrant
• Fact extraction hooks (src/personas/hooks/)
  • Session lifecycle hook for auto-extraction
  • Heuristic and LLM-based extraction

3.3 MCP Servers - COMPLETE

• Context7 integration
• Custom MCP for personas (src/mcp/servers/)
  • Memory MCP (personas-memory) - store, search, list, delete, stats
  • Calendar MCP (personas-calendar) - events, create, update, delete, free-time
  • Portfolio MCP (personas-portfolio) - status, positions, market-data, SEC, backtest

---

Phase 4: TUI Improvements

4.1 Model Selection - COMPLETE

• Favorites system (dialog-model.tsx favorites support)
• Recently used models (local.model.recent())
• Provider status indicators (auth valid/expired) - shows ✗/△ in model dialog
• Cost display for non-free models (shows "Free" badge)

4.2 Agent Experience - COMPLETE

• Agent-specific themes/colors (agent YAML theme field, auto-switch on agent change)
• Persistent agent state across sessions (via ContinuityManager)
• Agent handoff (delegate to another persona via <leader>d or command palette)

4.3 Conversation - COMPLETE

• Better compaction summaries (via continuity.ts generateSummary)
• Conversation branching (fork API + visual branch tree in sidebar + breadcrumb navigation)
• Export conversations (<leader>x to export, copy transcript command)

---

Phase 5: Upstream Sync - COMPLETE

5.1 Merge Strategy

• Track upstream OpenCode releases
  • Set up upstream remote: git remote add upstream https://github.com/sst/opencode
  • Create release tracking script (scripts/check-upstream.sh)
  • Document version mapping (docs/UPSTREAM-SYNC.md)
• Maintain patch set for agent-core customizations
  • Document divergence categories (patches/agent-core/README.md)
  • Store patches structure in patches/agent-core/
  • Create sync script (scripts/sync-upstream.sh)
• Automated conflict detection
  • Pre-merge conflict check in sync script
  • CI workflow for upstream sync PRs (.github/workflows/upstream-sync.yml)
  • Conflict resolution documentation (docs/UPSTREAM-SYNC.md)

5.2 Divergence Points (Document & Track)

Divergence	Files Affected	Complexity
Built-in agents removed	src/agent/, config	Low
Config paths (agent-core)	Global paths, CLI	Medium
Custom provider transforms	src/provider/	High
Persona skills	.claude/skills/	Low (additive)
Custom themes (zee/stanley/johny)	context/theme/	Low
Memory/Qdrant integration	src/memory/	Medium
Tiara orchestration	vendor/tiara/	Low (submodule)

5.3 Sync Workflow

• Create scripts/sync-upstream.sh automation
  • Fetch upstream tags
  • Compare against current base
  • Generate diff report
  • Preview/merge modes
• Document manual intervention points (docs/UPSTREAM-SYNC.md)
• Post-merge validation script (scripts/validate-sync.sh)

---

Phase 6: Cross-Platform Integration

6.1 Existing Platforms

Platform	Status	Location
TUI (agent-core)	✅ Primary	This repo
Web (OpenCode)	✅ Upstream	opencode-ai/opencode
Mobile (Zee)	✅ Companion	personas/zee mobile app

6.2 Integration Points - COMPLETE

• Shared session state across platforms
  • Session storage in JSON files with WAL
  • Real-time sync via SSE (/session/:id/events, /events)
  • Conflict resolution: last-write-wins, append-only messages
• Unified authentication
  • OAuth tokens in ~/.local/share/agent-core/auth.json
  • Session handoff API (POST /session/:id/handoff)
• Cross-platform notifications
  • Unified notify endpoint (POST /notify)
  • Telegram/WhatsApp broadcast support
  • Global event stream for dashboard monitoring

6.3 Mobile App Enhancement (Zee)

• Deep linking to specific sessions (agentcore://session/:id)
• Quick actions from notifications (via handoff API)
• Offline mode with sync queue
• Voice input integration

6.4 Web Interface (OpenCode)

• Persona switching in web UI
• Theme sync with TUI preferences
• Memory search interface
• Drone monitoring dashboard (via /events SSE)

Documentation: docs/CROSS-PLATFORM.md

---

Backlog

Nice to Have

• Voice input/output (Whisper/TTS integration)
• Multi-user support (shared Qdrant namespaces)
• Plugin marketplace for personas
• Canvas/whiteboard for visual reasoning

Platform Status

• Desktop → TUI (this repo)
• Mobile → Zee mobile app
• Web → OpenCode web

Technical Debt

• Remove "opencode" references in new code
• Type safety for persona configs
• Test coverage for provider transforms
• E2E tests for auth flows
• Consolidate auth storage paths (opencode vs agent-core)

---

Contributing

When working on roadmap items:

1. Create a branch: feat/phase-X.Y-description
2. Update this roadmap with progress
3. Add documentation to docs/
4. Test with all three personas