write agents.md in qwen's own words

agents.md

@@ -1,115 +1,48 @@
-# Claude Code Agents
+# Docster — Project Guide
 
-This project uses specialized Claude Code agents for different types of Haskell refactoring. Each agent has focused expertise to provide targeted improvements.
+Docster is a Haskell CLI tool: Markdown + embedded Mermaid diagrams → PDF, HTML, or DOCX.
 
-## Available Agents
+## Quick Commands
 
-### haskell-refactoring-expert
-**Purpose**: Basic code quality and structural improvements
-
-**Expertise**:
-- Type consistency (String vs Text vs ByteString)
-- Module organization and file splitting (>150 lines)
-- Naming conventions and clarity
-- Dependency management
-- Basic code structure improvements
-
-**When to use**: 
-- Inconsistent type usage across the codebase
-- Large files that need module organization
-- Poor naming or unclear function responsibilities
-- Mixed concerns in single modules
-
-**Example**: Converting a 300-line Main.hs into proper module hierarchy
-
-### haskell-higher-order
-**Purpose**: Advanced functional programming patterns and architectural refactoring
-
-**Expertise**:
-- Monad transformer patterns (ExceptT, ReaderT, StateT)
-- Pipeline composition with monadic operators
-- Higher-order abstractions and strategy patterns
-- Effect management and pure/IO separation
-- Functional design patterns
-
-**When to use**:
-- Nested case statements handling Either values in IO
-- Duplicated functions that differ only in specific steps
-- Manual threading of configuration or state
-- Imperative-style code that could be more functional
-- Complex error handling that needs cleanup
-
-**Example**: Converting nested Either/IO handling to ExceptT pipelines
-
-## Agent Boundaries and Trade-offs
-
-### Complementary Design
-These agents are designed to work **sequentially**:
-1. **First pass**: `haskell-refactoring-expert` for structural cleanup
-2. **Second pass**: `haskell-higher-order` for functional patterns
-
-### Why Separate Agents?
-
-**Benefits**:
-- **Focused expertise**: Each agent has deep knowledge in its domain
-- **Clear boundaries**: Easy to know which agent to use
-- **Manageable complexity**: Avoids instruction bloat in single agent
-- **Progressive enhancement**: Apply increasingly sophisticated refactoring
-- **Composability**: Can run both agents or just one as needed
-
-**Trade-offs**:
-- **Coordination overhead**: Need to run multiple agents
-- **Context switching**: Each agent analyzes code independently
-- **Potential overlap**: Some patterns might fit both agents
-
-### Decision Framework
-
-**Use haskell-refactoring-expert when you have**:
-- ❌ Mixed String/Text types
-- ❌ Large monolithic files (>150 lines)  
-- ❌ Unclear naming or responsibilities
-- ❌ Basic structural issues
-
-**Use haskell-higher-order when you have**:
-- ❌ Nested error handling (Either in IO)
-- ❌ Duplicated function structures
-- ❌ Manual state/config threading
-- ❌ Imperative-style patterns
-
-**Use both agents when**:
-- ❌ You want comprehensive refactoring
-- ❌ Code has both structural and architectural issues
-- ❌ You're doing major codebase improvements
-
-## Usage Patterns
-
-### Sequential Refactoring
 ```bash
-# Run basic refactoring first
+stack build          # build
-/agent haskell-refactoring-expert "Please refactor the Main.hs file"
+stack test           # run tests
-
+stack exec docster -- -pdf file.md   # convert to PDF
-# Then apply advanced patterns  
+stack exec docster -- -html file.md  # convert to HTML
-/agent haskell-higher-order "Please improve the error handling patterns"
+stack exec docster -- -docx file.md  # convert to DOCX
+stack exec docster -- -pdf sample.md # test with a single file
+stack clean          # clean build artifacts
 ```
 
-### Targeted Improvements
+## Structure
-```bash
-# Just structural cleanup
-/agent haskell-refactoring-expert "Split this large module"
 
-# Just functional patterns
+```
-/agent haskell-higher-order "Convert these nested cases to monadic style"
+docster.cabal        # package definition
+stack.yaml           # GHC 9.12.2, lts-24.34
+app/Main.hs          # everything — entry point + all logic (~70 lines)
+test/                # HSpec tests (TransformSpec.hs)
 ```
 
-## Evolution Strategy
+## How It Works
 
-These agents can evolve independently:
+1. Parse Markdown via Pandoc AST
-- **haskell-refactoring-expert**: Add more structural patterns, linting rules
+2. Walk the AST, find Mermaid code blocks
-- **haskell-higher-order**: Add more advanced patterns (free monads, effect systems)
+3. Run `mmdc` (mermaid-cli) to render each block → SVG (for HTML) or high-res PNG (for PDF)
+4. Replace code blocks with image references in the AST
+5. Compile final output via Pandoc (LaTeX/XeLaTeX for PDF, native for HTML/DOCX)
 
-New specialized agents could be added:
+Key functions in `Main.hs`:
-- **haskell-performance**: Optimization-focused refactoring
+- `transformDoc` — AST walker
-- **haskell-testing**: Test-driven refactoring and property-based testing
+- `processMermaidBlock` — calls `mmdc`, returns image reference
-- **haskell-domain**: Domain modeling and type design
+- `compileToPDF` / `compileToHTML` / `compileToDOCX` — final Pandoc compilation
 
-The key is maintaining clear boundaries and complementary functionality.
+## Dependencies
+
+**System**: TeX Live (for PDF), `npm install -g @mermaid-js/mermaid-cli`
+**Haskell**: Pandoc library, Stack manages GHC automatically
+
+## Common Gotchas
+
+- **Text vs String**: Codebase mixes `Data.Text` and `String`. Use `T.pack`/`T.unpack` for conversions.
+- **PDF needs LaTeX**: BasicTeX/TinyTeX + `tlmgr` for missing packages.
+- **mmdc in PATH**: `mermaid-cli` must be globally installed and on PATH.