Skip to content

CLAUDE.md

Latest commit

 

History

History
80 lines (63 loc) · 5.93 KB

CLAUDE.md

File metadata and controls

80 lines (63 loc) · 5.93 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

This repository contains standalone HTML templates for generating formatted documents, plus a CLI tool (llmrt) that renders markdown with YAML frontmatter and colon-fence directives into those templates.

CLI Tool (llmrt)

  • Install: pip install -e . from repo root
  • Render: llmrt render input.md -o output.html (use - for stdin)
  • Show example: llmrt template conversation, llmrt template report, or llmrt template session
  • Stack: Typer, markdown-it-py + mdit-py-plugins, Jinja2, python-frontmatter
  • Source: src/llmrt/ — cli.py, frontmatter.py, parser.py, renderer.py, toc.py
  • Templates: src/llmrt/templates/ — base.html.j2, conversation.html.j2, report.html.j2, session.html.j2
  • Tests: python -m pytest tests/ (39 tests)
  • Errors: FrontmatterError raised on invalid frontmatter, caught by CLI layer

Spec Templates (in specs/)

report_template.html — Technical Report

  • Typography: IBM Plex Serif (body), IBM Plex Sans (UI elements), IBM Plex Mono (code)
  • Accent color: --accent: #8b2500 (dark red)
  • Placeholders: {{LANG}}, {{TITLE}}, {{SUBTITLE}}
  • Available CSS components: .eq-block (labeled equations), .def-box (definition lists), .callout (warnings/notes), .arch-diagram (monospace diagrams), .fig (figure with caption), .algorithm (algorithm pseudocode), details (collapsible sections), .references (bibliography)
  • Syntax highlighting via Highlight.js — use <pre><code class="language-python"> for language hints
  • Sections are numbered manually in <h2> text (e.g., <h2>1. Section Title</h2>)

conversation_archive_template.html — Conversation Archive

  • Typography: IBM Plex Sans (body), IBM Plex Mono (code), IBM Plex Serif (available for shared components)
  • Accent color: same --accent: #8b2500
  • Placeholders: {{LANG}}, {{TITLE}}, {{DATE}}, {{N_EXCHANGES}}, {{TOPICS}}, {{TOC_ITEMS}}, {{MESSAGES}}
  • Messages use .message.human / .message.assistant classes with .role-badge headers
  • Shared components available inside .message-body: .eq-block, .def-box, .callout, .arch-diagram, .fig, .algorithm, details
  • Syntax highlighting via Highlight.js
  • Reasoning traces and tool calls should be excluded from archives

session.html.j2 — Session Document (plan / report / review)

  • For Claude Code session artifacts saved to agents/session-logs/
  • Typography: IBM Plex Sans (body), IBM Plex Mono (code)
  • Accent colors: Blue (#2e5a88) plan, Green (#4a7c3f) report, Amber (#8b5e3c) review
  • Frontmatter fields: type: session, kind (plan|report|review), title, date (optional), lang (optional)
  • Auto-detect mode: Raw markdown files with heading patterns (# Plan: ..., # Implementation Report: ..., # Code Review: ...) are detected automatically without frontmatter
  • Extracts **Date:** from first ~15 lines when auto-detecting
  • Shared directives available: .callout, .eq-block, .def-box, .arch-diagram, .fig, .algorithm, .details
  • TOC generated client-side from all h2/h3 headings (no digit-prefix filter)
  • Distinct from type: report which is for formal technical reports with Serif typography

Directive Syntax (for llmrt markdown input)

Colon-fence directives map to CSS components: :::{.name key="value"} ... :::

  • Conversation-only: :::{.human}, :::{.assistant} (attr: timestamp), :::{.thinking} (attr: duration)
  • Report-only: :::{.references} — use [[N]](#ref-N) for in-text citations and <a id="ref-N">[N]</a> for reference anchors
  • Shared: :::{.callout} (attr: type: Scope, Note, Important, Tip, Warning, Decision, Reviewed), :::{.eq-block} (attr: label), :::{.def-box}, :::{.arch-diagram}, :::{.fig} (attr: caption), :::{.algorithm} (attr: title), :::{.details} (attr: summary)
  • Use :::: (4-colon) for outer containers that nest inner ::: (3-colon) directives

Conventions

  • All templates use the IBM Plex font family (Serif, Sans, Mono) via Google Fonts.
  • All templates use KaTeX (v0.16.9 via CDN) for math rendering with $inline$ and $$display$$ delimiters.
  • All templates use Highlight.js (v11.9.0 via CDN, github theme) for syntax highlighting.
  • All templates use Mermaid.js (v11 via CDN, neutral theme) for diagram rendering. Use ```mermaid code fences for flowcharts, sequence diagrams, and architecture layouts.
  • All templates include @media print rules for clean PDF output.
  • Section separators use <!-- === --> HTML comments.
  • All CSS is self-contained in <style> blocks (no external stylesheets beyond fonts, KaTeX, and Highlight.js).

Workflow Rules

  • No automatic commits. Claude must never commit on its own. All commits are made by the user.

  • Persist agent artifacts. All design, planning, and review documents are saved to agents/session-logs/ with the naming convention agents/session-logs/{YYYY-MM-DD}-{name}-{stage}.md. The stages follow this lifecycle:

    1. {date}-{name}-design.md — Brainstorm / design exploration (before planning)
    2. {date}-{name}-plan.md — Concrete implementation plan (must exist before execution begins)
    3. {date}-{name}-report.md — Implementation report (saved after executing the plan)
    4. {date}-{name}-review.md — Code review and verification (saved after reviewing the work)

    Saving the plan is the very first task when exiting plan mode. Immediately upon exiting plan mode, before any implementation work begins, save the plan to agents/session-logs/{date}-{name}-plan.md. This is non-negotiable — no code is written until the plan file exists on disk. Never execute a plan that has not been written to disk first.

  • Ultrathink on design, brainstorm, plan, and review. Claude must use extended thinking (ultrathink) during design, brainstorm, planning, and review stages to ensure deep, thorough reasoning.