agent-evals/SPEC.md

WYSIWYG Markdown Editor - Specification

Overview

Build a WYSIWYG markdown editor with save functionality consisting of a Go backend and vanilla JavaScript frontend with Tailwind CSS.
Beyond the listed features, no authentication, user accounts, collaborative editing, or version history are required.

Backend (Go)

Requirements

• Use Go with standard HTTP server
• Use Cobra library for CLI argument parsing
• Implement CRUD operations for markdown files:
  • Create: Add new markdown files
  • Read: Retrieve/View markdown files
  • Update: Edit existing markdown files
  • Delete: Remove markdown files
• Store markdown files on disk in a specified directory
• The server must handle concurrent requests safely; the last successful write wins
• Markdown file names are case-sensitive and must end in .md. Illegal characters for the current OS must be rejected with 400 Bad Request
• Directory structure under --data-dir is flat: every .md file is a sibling; sub-directories are ignored

CLI Options

The application must support the following CLI flags:

• --data-dir: Path to the directory where markdown files will be stored (default: ./data)
• --port: Port number to run the HTTP server on (default: 8080)
• --host: Host address to bind to (default: 127.0.0.1)
  Cobra must generate help text for --help and -h that includes defaults.

API Implementation

• Design and implement appropriate REST endpoints for CRUD operations
• Handle error responses appropriately
• Validate inputs appropriately
• Any operation that fails must return an HTTP 4xx/5xx code and a JSON body containing at least an error string

Frontend (Vanilla JavaScript + Tailwind CSS)

Requirements

• Vanilla JavaScript (no frameworks)
• Tailwind CSS for styling
• Single-page application interface
• No build step except running the Tailwind CLI once to generate the CSS file; runtime must work in a current Chrome/Edge/Firefox without polyfills

Features

Markdown Editor

• Split-view or toggleable view with:
  • Edit pane: Textarea for markdown input
  • Preview pane: Rendered markdown preview
• Real-time preview updates
• Render markdown with GitHub-Flavored-Markdown (GFM) semantics

Theme Support

Three theme modes:

• Dark: Dark color scheme
• Light: Light color scheme
• System: Follows system preference

Theme switching requirements:

• Auto-detect system preference on load (prefers-color-scheme)
• Manual theme switcher with three options: Dark, Light, System
• Persist theme preference in localStorage under the key wysiwyg-theme
• Update theme immediately when changed
• Respect system theme changes when in "System" mode

File Management UI

• List all markdown files
• Create new files
• Open existing files for editing
• Save changes
• Delete files

Responsive Design

• Works on desktop and mobile
• Responsive layout using Tailwind classes

Development Environment

The repository root contains a flake.nix locked to github:NixOS/nixpkgs/nixos-25.11.
nix develop has already been executed; the resulting shell provides:

• go, gopls, golangci-lint
• tailwindcss
• gnumake

You must not modify the flake or add packages outside this environment.

General Requirements

• No database - use file system
• Minimal dependencies
• Clean, maintainable code
• Proper error handling

Testing & Observability

• Provide at least one automated test (unit, integration, or end-to-end) that can be run with a single command (go test, make test, etc.).
• The test must demonstrate that a markdown file can be created, read, updated, and deleted through the REST endpoints.
• On start-up the server must log its bound address in the format listening on <host>:<port> so evaluators can script against it.

Evaluation Checklist

Evaluation will check:
(1) CLI starts with defaults,
(2) CRUD round-trip,
(3) theme switch & persistence,
(4) responsive layout on 320 px and 1920 px,