xonecas.io
60255
Zn

Zoea-Nova / commit b1a0a2d

chore: AGENTS too

xonecas2026-02-09 b1a0a2df58ecc83c45954553890f7b3cd5d702cc parent ff030c9

1 file changed

AGENTS.md+0−226
@@ -1,226 +0,0 @@
1-# Zoea Nova Agents
2-
3-Guidelines for AI agents working on Zoea Nova—a TUI-based swarm controller for automated SpaceMolt game players.
4-
5-## Critical Rules
6-
7-**YOU MUST**:
8-
9-- **NEVER edit `documentation/current/TODO.md`** - User managed only
10-- Not change game server API - document issues in `documentation/current/KNOWN_SERVER_ISSUES.md`
11-- Not commit to git without explicit user approval - ask first
12-- When committing, use non-interactive git commands (always use `-m` flag, never open editors)
13-- Use Go 1.22+ idioms, no CGO
14-- Keep code in `internal/`, only `cmd/zoea/main.go` is public
15-- Use interfaces for external dependencies (LLM providers, MCP, store)
16-- Run `make fmt` before committing, fix all warnings/linter errors
17-- Write unit tests for all modules (target 80%+ coverage, currently ~83%)
18-- Use `zerolog` for logging, never log to stdout/stderr (TUI owns terminal)
19-- Keep TUI responsive - all LLM/network calls non-blocking (goroutines + channels)
20-- Follow Bubble Tea Elm Architecture: Model → Update → View
21-- Keep scope minimal (MVP), but maintain testing and code quality
22-- Keep `documentation/current/KNOWN_ISSUES.md` up-to-date
23-- Use AGENTS.md for technical info (not guides), README.md for user-facing info
24-
25-## Versions
26-
27-- Version format: `vMAJOR.MINOR.PATCH`
28-- Start at `v0.1.0`
29-- MAJOR: breaking changes or required database reset
30-- MINOR: new features
31-- PATCH: fixes, refactors, docs, chores
32-- Release tags must be annotated
33-
34-## Offline Mode
35-
36-Run without SpaceMolt MCP server: `./bin/zoea --offline`
37-
38-Uses stub MCP client with mock data. See `documentation/architecture/OFFLINE_MODE.md` for details.
39-
40-## Terminal Requirements
41-
42-**Minimum:** 80 columns × 20 lines
43-
44-**Recommended terminals:** Alacritty, Kitty, WezTerm, Ghostty, iTerm2, Windows Terminal
45-
46-**Fonts:** Nerd Fonts (FiraCode, JetBrains Mono) or Unicode fonts (Cascadia Code, Ubuntu Mono)
47-
48-See `documentation/guides/TERMINAL_COMPATIBILITY.md` and `documentation/guides/TUI_TESTING.md`.
49-
50-## TUI Testing
51-
52-Zoea Nova uses three types of TUI tests:
53-
54-### 1. Unit Tests (Model State & Logic)
55-
56-Test model state transitions, business logic, and non-rendering behavior:
57-
58-- Navigation (up/down, view switching)
59-- Input mode transitions
60-- Help toggle, history navigation
61-- Error handling
62-
63-### 2. Golden File Tests (Visual Regression)
64-
65-Test visual output using golden files (both ANSI and stripped versions):
66-
67-- Dashboard rendering
68-- Focus view layouts
69-- Log entry formatting
70-- JSON tree rendering
71-- Scrollbar positioning
72-
73-**Update golden files:** `go test ./internal/tui -update`
74-
75-### 3. Integration Tests (End-to-End with teatest)
76-
77-Test full TUI behavior through Bubble Tea's event loop:
78-
79-- Complete user flows (create mysis, send broadcast, etc.)
80-- Async event handling
81-- Window resize behavior
82-- Viewport scrolling
83-
84-### Testing Guidelines
85-
86-- **DO NOT test width arithmetic** - Terminal rendering is complex and environment-dependent
87-- **DO NOT test ANSI codes directly** - Use golden files for visual tests
88-- **DO test model state** - Navigation, mode changes, data transformations
89-- **DO use teatest for integration** - Test actual user interactions
90-- **DO use golden files for visuals** - Snapshot testing for UI regression
91-
92-### Lipgloss Testing Notes
93-
94-- **Force color output**: Use `setupGoldenTest(t)` helper for consistent ANSI output
95-- **Use `lipgloss.Width()` for display width**: Never use `len()` on styled strings
96-- **Strip ANSI for content checks**: Use `stripANSIForGolden()` helper
97-
98-## Unicode Width Calculations
99-
100-Multi-byte Unicode characters cause width calculation bugs:
101-
102-- **`len()` returns BYTES, not display width**: Characters like `◈`, `◆`, `╭`, `─` are 3 bytes each but display as 1 column. Using `len()` for width calculations produces incorrect results.
103-- **ALWAYS use `lipgloss.Width()`**: This correctly calculates display width for both Unicode and ANSI-styled strings.
104-- **Test with Unicode-heavy content**: Section titles and decorative borders use Unicode box-drawing characters. Always test width calculations with actual Unicode content.
105-- **Panel alignment requires exact widths**: If a section title is `width` chars and a panel border is calculated with `len()` instead of `lipgloss.Width()`, they will visually misalign.
106-- **Style padding affects alignment**: `lipgloss.Style.Padding(0, 1)` adds 1 space on each side. If one element has padding and another doesn't, their decorations won't align even if both are "width" chars total.
107-- **`lipgloss.Width()` sets content width**: When using `style.Width(n)`, the `n` sets the CONTENT width. Borders and padding are added ON TOP. So `style.Width(98)` with a border produces total width 100.
108-
109-## Database Management
110-
111-The application uses SQLite for persistence.
112-
113-- **Location**: `~/.zoea-nova/zoea.db`
114-- **Querying**: Use `sqlite3 ~/.zoea-nova/zoea.db` to run manual queries.
115-- **Wiping**: To reset state or apply schema changes (no migrations), run `make db-reset-accounts` to export usernames/passwords to `accounts-backup.sql`, wipe the DB, recreate schema, and reimport accounts. The backup file is created at repo root and is ignored by git.
116-- **Testing**: Tests use `t.TempDir()` for isolated database files. Never use the production database path in tests.
117-
118-## Terminology
119-
120-- **Mysis**: An AI-controlled player instance with its own provider, memory, and state.
121-- **Commander**: The swarm orchestrator that owns Mysis lifecycles and routes messages.
122-- **Swarm**: The collection of all Myses managed by the Commander.
123-- **Broadcast**: A message sent to all running myses except the sender. Stored with sender_id for tracking.
124-- **Provider**: An LLM backend (Ollama local or OpenCode Zen remote).
125-- **MCP**: Model Context Protocol—the interface to SpaceMolt game actions.
126-- **Event Bus**: Channel-based pub/sub for TUI updates from core goroutines.
127-- **Focus Mode**: TUI view showing detailed conversation logs for a single Mysis.
128-- **Dashboard**: TUI view showing swarm status, broadcast history, and Mysis list.
129-- **Memory**: A stored conversation message with role (system/user/assistant/tool) and source.
130-- **Memory Source**: Origin of a memory—`direct` (single Mysis), `broadcast` (swarm), `system`, `llm`, or `tool`.
131-- **Context Compression**: Sliding window that sends only recent messages + system prompt to LLM. See [documentation/architecture/CONTEXT_COMPRESSION.md](documentation/architecture/CONTEXT_COMPRESSION.md).
132-
133-## Architecture
134-
135-```mermaid
136-flowchart LR
137- TUI["TUI (Bubble Tea)"] -->|events| EventBus["Event Bus"]
138- EventBus --> Commander
139- Commander -->|manages| Mysis
140- Mysis --> Provider
141- Provider --> LLM
142- Commander --> Store
143- Mysis --> Store
144- Mysis --> MCPProxy["MCP Proxy"]
145- MCPProxy --> SpaceMolt["SpaceMolt MCP Server"]
146-```
147-
148-## Provider Architecture
149-
150-Zoea Nova supports two types of LLM providers:
151-
152-### OpenAI-Compatible Providers
153-
154-Providers that follow the [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat/create) specification.
155-
156-**Examples:** OpenCode Zen, OpenAI, Azure OpenAI, Together AI, etc.
157-
158-**Implementation:**
159-
160-- Use shared code in `internal/provider/openai_common.go`
161-- Strict message ordering (system first, alternating user/assistant)
162-- Tool call validation and orphaned message removal
163-- Fallback user message if only system messages exist
164-
165-**Location:** `internal/provider/opencode.go` (reference implementation)
166-
167-### Ollama Provider
168-
169-Custom provider with flexible API that differs from OpenAI standard.
170-
171-**Ollama-Specific Behavior:**
172-
173-- System messages allowed anywhere (not just first)
174-- Custom response types with `reasoning()` method
175-- Flexible message ordering
176-
177-**Implementation:**
178-
179-- Isolated in `internal/provider/ollama.go`
180-- Uses custom types (`ollamaReqMessage`, `chatCompletionResponse`, etc.)
181-- Custom message merging (`mergeConsecutiveSystemMessagesOllama`)
182-- **DO NOT** use Ollama code for OpenAI-compatible providers
183-
184-**Location:** `internal/provider/ollama.go`
185-
186-### Key Files
187-
188-- `internal/provider/openai_common.go` - Shared OpenAI-compliant code (use for new OpenAI-compatible providers)
189-- `internal/provider/opencode.go` - OpenCode Zen implementation (OpenAI-compatible reference)
190-- `internal/provider/ollama.go` - Ollama implementation (isolated, custom)
191-- `documentation/architecture/OPENAI_COMPATIBILITY.md` - Full compatibility guide
192-
193-### Adding New Providers
194-
195-- **OpenAI-compatible:** Use `openai_common.go` functions, follow OpenCode pattern
196-- **Custom API:** Create isolated implementation like Ollama, document differences
197-
198-## State Machine
199-
200-See `documentation/architecture/MYSIS_STATE_MACHINE.md` for valid Mysis transitions and triggers.
201-
202-## Workflow
203-
204-The user follows a structured development workflow. Respect these phases:
205-
206-1. **Design**: Documentation for this project is in `documentation/` Keep it up to date and accurate.
207-2. **Plan**: Complex changes require a plan in `.opencode/plans/`. Reference the plan while implementing.
208-3. **Implement**: Follow the plan phase-by-phase. Update tests alongside code, add more as needed.
209-4. **Test**: Run `make test` after each phase. Fix failures before moving on.
210-5. **Build**: Run `make build` to verify compilation. Address any warnings.
211-
212-## Role
213-
214-You are helping build a retro-futuristic TUI command center for controlling AI game Myses. Assume familiarity with:
215-
216-- Go concurrency patterns (goroutines, channels, select)
217-- Bubble Tea / Elm Architecture (Model, Update, View, Cmd, Msg)
218-- SQLite basics (no ORM, raw SQL is fine)
219-- OpenAI-compatible APIs (chat completions, streaming)
220-
221-Do NOT assume knowledge of:
222-
223-- SpaceMolt game mechanics (refer to MCP tool schemas)
224-- Internal project state (always read relevant files first)
225-
226-When in doubt, ask. Don't guess at requirements or invent features.