agent-evals/SPEC.md

WYSIWYG Markdown Editor - Specification

Overview

Build a markdown editor with preview: Go backend + React/TypeScript frontend with Tailwind CSS.

Out of scope: authentication, user accounts, collaborative editing, version history.

Backend (Go)

• Standard HTTP server + Cobra for CLI
• CRUD REST API for markdown files
• Store files on disk (flat structure, .md files only)
• Errors return 4xx/5xx + JSON with error field
• Comprehensive logging using logrus

CLI Flags

• --data-dir: Storage path (default: ./data)
• --port: Server port (default: 8080)
• --host: Bind address (default: 127.0.0.1)

Frontend (React + TypeScript + Tailwind)

• Markdown editor with live GFM preview
• File management: list, create, open, save, delete
• Three themes (Dark, Light, System) with switcher
• Responsive (desktop + mobile)

Development Environment

flake.nix (locked to nixos-25.11) provides: go, gopls, golangci-lint, eslint, nodejs, gnumake, lsof

Do not modify flake.

Testing (TDD)

• All tests must pass
• Single command to run tests
• Backend: demonstrate CRUD round-trip + static asset serving
• Frontend: verify core functionality

Milestones

Backend (6 milestones)

B1: CLI & Server Setup

• Cobra CLI with --data-dir, --port, --host flags
• HTTP server with basic routing

B2: CRUD API

• REST endpoints for markdown files (GET, POST, PUT, DELETE)
• JSON error responses (4xx/5xx)

B3: File Storage

• Read/write .md files to disk
• Flat file structure

B4: Logging

• Comprehensive logrus logging for all operations

B5: Static Assets

• Serve frontend build files

B6: Backend Tests

• CRUD round-trip tests
• Static asset serving tests

Frontend (6 milestones)

F1: Project Setup

• React + TypeScript + Tailwind configured

F2: File Management UI

• List, create, open, save, delete markdown files

F3: Editor & Preview

• Markdown editor with live GFM preview

F4: Theme System

• Dark/Light/System themes
• Theme switcher and persistence

F5: Responsive Design

• Works at 320px and 1920px

F6: Frontend Tests

• Core functionality tests (editor, file operations, themes)

Integration (1 milestone)

I1: End-to-end

• Full CRUD workflow test from frontend to backend

Evaluation

1. CLI starts with defaults
2. CRUD works end-to-end
3. Static assets are properly served
4. Theme switch & persistence
5. Responsive at 320px and 1920px