Skip to content

CLAUDE.md

Latest commit

 

History

History
67 lines (52 loc) · 2.33 KB

CLAUDE.md

File metadata and controls

67 lines (52 loc) · 2.33 KB

OpenSpec Viewer

Interactive browser viewer for OpenSpec directories.

Project Structure

openspec-viewer/
├── bin/openspec-viewer.js    # CLI entry point
├── src/                      # Backend TypeScript source
│   ├── cli/                  # CLI argument parsing
│   ├── server/               # Fastify server + WebSocket
│   ├── watcher/              # chokidar file watching
│   ├── parser/               # OpenSpec markdown parsing
│   └── shared/               # Shared types
├── frontend/                 # Svelte frontend
│   └── src/
│       ├── components/       # Svelte components
│       ├── stores/           # Svelte stores
│       └── lib/              # Utilities
├── dist/                     # Built backend (gitignored)
└── dist-frontend/            # Built frontend (gitignored)

Development

npm install
npm run dev          # Run both server and frontend in dev mode
npm run build        # Build for production

Tech Stack

  • Backend: Fastify, ws (WebSocket), chokidar (file watching)
  • Frontend: Svelte 5, Tailwind CSS
  • Build: TypeScript, Vite

Code Conventions

  • Use TypeScript strict mode
  • Use ES modules (type: "module")
  • Prefer async/await over callbacks
  • Keep components small and focused

OpenSpec Format

OpenSpec is a specification-driven development framework with:

  • project.md - Project conventions
  • specs/ - Current specifications (what IS built)
  • changes/ - Proposals for changes (what SHOULD change)
    • proposal.md, tasks.md, design.md - Each gets its own tab
    • specs/ subdirectory with delta changes (ADDED/MODIFIED/REMOVED)
    • mockups/ or any subdirectory - HTML/MD files grouped by folder
  • changes/archive/ - Completed changes with date prefix

File Rendering

The viewer supports rendering arbitrary .md and .html files in change directories:

  • Markdown files: Rendered with syntax highlighting and GitHub-flavored markdown
  • HTML files: Rendered in sandboxed iframes with full CSS/JS support

Files are organized into tabs:

  1. Core files (proposal.md, tasks.md, design.md) each get their own tab
  2. Files in subdirectories are grouped by folder name (e.g., mockups/ becomes "Mockups" tab)
  3. Spec deltas appear in the final "Spec Deltas" tab