| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 5 | 22 | 0% |
| Commands | 0 | 6 | 0 | 0% |
| Section tags | 3 | 0 | 1 | 75% |
What each file covers
Sections
0 shared · 5 only in A · 22 only in B- − Gemini Agent Guide for Hermes
- − Project Overview & Architecture
- − Developer Workflow
- − Key Development Patterns
- − Gemini Agent Specific Notes
- + Cursor MDC File Guidelines
- + File Structure
- + 1. Frontmatter
- + 2. Metadata Annotations
- + 3. Content Structure
- + Best Practices
- + Implementation Guidelines
- + Example Structure
- + Basic Example
- + Feature X Implementation
- + Overview
- + Implementation
- + Usage Examples
- + Full Implementation Example
- + Common Patterns
- + Examples
- + Minimal Valid MDC File
- + Example Rules
- + Section One
- + Common Section Examples
- + Common Mistakes to Avoid
- + Validation
Commands
0 shared · 6 only in A · 0 only in B- − task build
- − task test
- − task lint
- − go run . <command> [flags]
- − go run . import goodreads -f path/to/export.csv
- − go.mod
Section tags
3 shared · 0 only in A · 1 only in B- + do-not
- code-style
- architecture
- agent-behaviour
Line diff
lepinkainen/hermes · GEMINI.md
@@ −1 @@
1# Gemini Agent Guide for Hermes
2
3This guide provides essential information for developing in the Hermes codebase.
4
5## Project Overview & Architecture
6
7Hermes is a Go-based CLI tool for importing data from sources like Goodreads, IMDb, and Steam, and exporting it into Markdown, JSON, or SQLite/Datasette formats.
8
9- **Entrypoint**: `main.go` calls `cmd.Execute()` to start the Kong CLI application.
10- **Commands (`cmd/`)**: Each data importer is a self-contained package within a subdirectory (e.g., `cmd/goodreads/`, `cmd/steam/`). This is the primary location for adding or modifying importer logic.
11- **Shared Logic (`internal/`)**: Contains reusable packages for common functionality:
12 - `config`: Viper-based configuration management.
13 - `fileutil`: Helpers for writing Markdown and JSON files.
14 - `datastore`: SQLite and Datasette integration.
15 - `errors`: Custom error types (e.g., for rate limiting).
16- **Configuration**: Managed via a `config.yaml` file. CLI flags take precedence over config file settings.
17- **Output**: Data is written to `json/` and `markdown/` directories by default.
18- **Caching**: API responses are cached in the `cache/` directory, with subdirectories for each importer, to minimize external calls.
19
20## Developer Workflow
21
22The project uses `Taskfile.yml` for task automation.
23
24- **Build & Test**: `task build` - This is the primary command for development. It automatically runs tests, lints the code, and compiles the binary to `build/hermes`.
25- **Run Tests**: `task test` - Runs all tests and generates a coverage report in `coverage/`.
26- **Lint Code**: `task lint` - Runs `golangci-lint`.
27- **Run the CLI**: For development, use `go run . <command> [flags]`. For example: `go run . import goodreads -f path/to/export.csv`.
28
29## Key Development Patterns
30
31- **Adding a New Importer**:
32 1. Create a new package under `cmd/`.
33 2. Mimic the structure of an existing importer (e.g., `cmd/goodreads`):
34 - `cmd.go`: Kong command definition.
35 - `parser.go`: Logic for parsing the source data file.
36 - `types.go`: Structs for the data models.
37 - `api.go` (or similar): Client for external APIs (e.g., OMDB, OpenLibrary).
38 - `cache.go`, `json.go`, `markdown.go`: Handlers for caching and output formats.
39 3. Add the new command to `cmd/root.go`.
40
41- **Error Handling**:
42 - Return errors up the call stack.
43 - Wrap errors with context using `fmt.Errorf("...: %w", err)` to provide a clear trace.
44 - Use custom error types from `internal/errors` where applicable.
45
46- **Utilities**:
47 - Always use helpers from `internal/` for common tasks like file writing (`fileutil`) and configuration (`config`).
48 - Contribute new, reusable logic back to the `internal/` packages.
49
50- **Dependencies**:
51 - The project uses Go modules. Key libraries include `kong` for the CLI, `viper` for configuration, and `modernc.org/sqlite` for the database. Add new dependencies to `go.mod` only when necessary.
52
53## Gemini Agent Specific Notes
54- Always use `task build` to build the project.
lepinkainen/hermes · .cursor/rules/mdc.mdc
@@ +1 @@
1---
2description: Guidelines and best practices for creating .mdc (Markdown Configuration) files in Cursor, including structure, metadata annotations, and formatting rules
3globs: **/*.mdc
4alwaysApply: false
5---
6# Cursor MDC File Guidelines
7
8@context {
9 "type": "documentation",
10 "purpose": "cursor_rules",
11 "format_version": "1.0.0",
12 "supported_content_types": [
13 "guidelines",
14 "api_docs",
15 "examples",
16 "implementations"
17 ]
18}
19
20@structure {
21 "required_sections": [
22 "frontmatter",
23 "title",
24 "context",
25 "content_sections"
26 ],
27 "optional_sections": [
28 "version",
29 "last_updated",
30 "examples",
31 "implementations",
32 "related_files"
33 ],
34 "recommended_sections": [
35 "practical_examples",
36 "common_patterns",
37 "type_definitions"
38 ]
39}
40
41## File Structure
42
43### 1. Frontmatter
44
45@frontmatter_rules [
46 {
47 "id": "position",
48 "rule": "Must be at the very top of the file",
49 "severity": "error"
50 },
51 {
52 "id": "description",
53 "rule": "Single sentence, clear purpose",
54 "severity": "error"
55 },
56 {
57 "id": "globs",
58 "rule": "Array of relevant file patterns",
59 "severity": "error"
60 },
61 {
62 "id": "related_docs",
63 "rule": "Optional array of related documentation files - MUST only reference existing files",
64 "severity": "error"
65 },
66 {
67 "id": "file_validation",
68 "rule": "All referenced files must exist in the workspace",
69 "severity": "error"
70 }
71]
72
73Example frontmatter:
74```yaml
75---
76description: Guidelines for implementing feature X
77globs: ["**/*.{ts,tsx}"]
78related_docs: ["docs/architecture/feature-x.md"]
79---
80```
81
82### 2. Metadata Annotations
83
84@annotations {
85 "syntax": "@annotation_name JSON_content",
86 "placement": "Before relevant sections",
87 "format": "Valid JSON with proper indentation",
88 "types": {
89 "context": "Project and document context",
90 "rules": "List of rules or requirements",
91 "format": "Format specifications",
92 "options": "Available options",
93 "examples": "Implementation examples",
94 "implementations": "Full implementation details",
95 "related": "Related documentation or code"
96 }
97}
98
99### 3. Content Structure
100
101@content_rules {
102 "headings": {
103 "h1": "Single main title",
104 "h2": "Major sections",
105 "h3": "Subsections",
106 "h4": "Detailed points"
107 },
108 "code_blocks": {
109 "syntax": "Always specify language",
110 "examples": "Include practical examples",
111 "formatting": "Use proper indentation",
112 "context": "Add explanatory comments"
113 },
114 "implementation_blocks": {
115 "structure": "Group related implementations",
116 "documentation": "Include inline documentation",
117 "types": "Specify type information",
118 "validation": "Include validation rules"
119 }
120}
121
122## Best Practices
123
124@best_practices {
125 "organization": {
126 "sections": "Use clear hierarchical structure",
127 "annotations": "Place before relevant content",
128 "examples": "Include practical examples"
129 },
130 "formatting": {
131 "json": "Properly formatted, valid JSON",
132 "markdown": "Clean, consistent spacing",
133 "code": "Language-specific syntax highlighting"
134 },
135 "metadata": {
136 "annotations": "Use semantic names",
137 "context": "Provide clear scope",
138 "versioning": "Include version information"
139 },
140 "implementation": {
141 "examples": "Provide complete, working examples",
142 "types": "Include type definitions",
143 "validation": "Specify validation rules",
144 "error_handling": "Document error cases"
145 }
146}
147
148## Implementation Guidelines
149
150@implementation_rules {
151 "code_examples": {
152 "completeness": "Must be fully functional",
153 "types": "Include all necessary type information",
154 "imports": "Show all required imports",
155 "context": "Provide setup and usage context"
156 },
157 "documentation": {
158 "inline": "Add explanatory comments",
159 "types": "Document type constraints",
160 "errors": "Document error conditions",
161 "usage": "Show usage patterns"
162 }
163}
164
165## Example Structure
166
167### Basic Example
168```markdown
169---
170description: Example implementation of feature X
171globs: ["src/features/**/*.ts"]
172---
173
174# Feature X Implementation
175
176@context {
177 "type": "implementation",
178 "feature": "X",
179 "version": "1.0.0"
180}
181
182## Overview
183[Feature description]
184
185## Implementation
186
187@implementation {
188 "language": "typescript",
189 "dependencies": ["dep1", "dep2"],
190 "types": {
191 "TypeX": "Description of TypeX"
192 }
193}
194
195```typescript
196// Implementation code with types and validation
197```
198
199## Usage Examples
200[Usage examples with code]
201```
202
203### Full Implementation Example
204See the `examples` section in related .mdc files for complete implementation examples.
205
206## Common Patterns
207
208@patterns {
209 "rules_section": {
210 "format": "array of objects",
211 "properties": ["id", "severity", "description"],
212 "example": [
213 {
214 "id": "rule_name",
215 "severity": "error",
216 "description": "Clear description"
217 }
218 ]
219 },
220 "implementation_section": {
221 "format": "object with implementation details",
222 "required": [
223 "language",
224 "types",
225 "validation"
226 ],
227 "example": {
228 "language": "typescript",
229 "types": {
230 "Type1": "Description"
231 },
232 "validation": {
233 "rule1": "Description"
234 }
235 }
236 }
237}
238
239## Examples
240
241### Minimal Valid MDC File
242```markdown
243---
244description: A simple example MDC file
245globs: ["**/*.example"]
246---
247
248# Example Rules
249
250@context {
251 "type": "example",
252 "version": "1.0.0"
253}
254
255## Section One
256
257@rules [
258 {
259 "id": "rule_one",
260 "severity": "error",
261 "description": "Description of rule one"
262 }
263]
264```
265
266### Common Section Examples
267
268#### Rules Section
269```markdown
270@rules [
271 {
272 "id": "unique_identifier",
273 "severity": "error|warning|info",
274 "description": "Clear description of the rule"
275 }
276]
277```
278
279#### Options Section
280```markdown
281@options {
282 "option_name": "What this option does",
283 "another_option": "Description of another option"
284}
285```
286
287#### Format Section
288```markdown
289@format {
290 "base": "Template with {placeholders}",
291 "options": ["array", "of", "options"],
292 "paths": {
293 "key": "value"
294 }
295}
296```
297
298### Common Mistakes to Avoid
299
300@mistakes [
301 {
302 "id": "missing_frontmatter",
303 "wrong": "Starting directly with content",
304 "correct": "Include frontmatter at top",
305 "reason": "Frontmatter is required for Cursor to properly parse the file"
306 },
307 {
308 "id": "invalid_json",
309 "wrong": "Malformed JSON in annotations",
310 "correct": "Properly formatted JSON with quotes around keys",
311 "reason": "Annotations must contain valid JSON for proper parsing"
312 },
313 {
314 "id": "inconsistent_structure",
315 "wrong": "Mixed levels of headings",
316 "correct": "Clear hierarchical structure",
317 "reason": "Consistent structure helps with readability and parsing"
318 },
319 {
320 "id": "nonexistent_files",
321 "wrong": "Referencing files that don't exist in the workspace",
322 "correct": "Only reference files that exist and have been verified",
323 "reason": "Prevents broken links and maintains documentation integrity"
324 }
325]
326
327## Validation
328
329@validation {
330 "required": [
331 "Frontmatter must be present and valid",
332 "All JSON must be properly formatted",
333 "Main title must be present",
334 "At least one content section",
335 "Complete implementation examples when relevant",
336 "All referenced files must exist in the workspace"
337 ],
338 "recommended": [
339 "Version information",
340 "Last updated date",
341 "Clear examples",
342 "Proper code formatting",
343 "Type definitions",
344 "Validation rules",
345 "Verify file existence before referencing"
346 ]
347}
348
349@version "1.1.0"
350@last_updated "2024-03-19"
@@ −1 +1 @@
1−# Gemini Agent Guide for Hermes
1+---
2+description: Guidelines and best practices for creating .mdc (Markdown Configuration) files in Cursor, including structure, metadata annotations, and formatting rules
3+globs: **/*.mdc
4+alwaysApply: false
5+---
6+# Cursor MDC File Guidelines
27
3−This guide provides essential information for developing in the Hermes codebase.
8+@context {
9+ "type": "documentation",
10+ "purpose": "cursor_rules",
11+ "format_version": "1.0.0",
12+ "supported_content_types": [
13+ "guidelines",
14+ "api_docs",
15+ "examples",
16+ "implementations"
17+ ]
18+}
419
5−## Project Overview & Architecture
20+@structure {
21+ "required_sections": [
22+ "frontmatter",
23+ "title",
24+ "context",
25+ "content_sections"
26+ ],
27+ "optional_sections": [
28+ "version",
29+ "last_updated",
30+ "examples",
31+ "implementations",
32+ "related_files"
33+ ],
34+ "recommended_sections": [
35+ "practical_examples",
36+ "common_patterns",
37+ "type_definitions"
38+ ]
39+}
640
7−Hermes is a Go-based CLI tool for importing data from sources like Goodreads, IMDb, and Steam, and exporting it into Markdown, JSON, or SQLite/Datasette formats.
41+## File Structure
842
9−- **Entrypoint**: `main.go` calls `cmd.Execute()` to start the Kong CLI application.
10−- **Commands (`cmd/`)**: Each data importer is a self-contained package within a subdirectory (e.g., `cmd/goodreads/`, `cmd/steam/`). This is the primary location for adding or modifying importer logic.
11−- **Shared Logic (`internal/`)**: Contains reusable packages for common functionality:
12− - `config`: Viper-based configuration management.
13− - `fileutil`: Helpers for writing Markdown and JSON files.
14− - `datastore`: SQLite and Datasette integration.
15− - `errors`: Custom error types (e.g., for rate limiting).
16−- **Configuration**: Managed via a `config.yaml` file. CLI flags take precedence over config file settings.
17−- **Output**: Data is written to `json/` and `markdown/` directories by default.
18−- **Caching**: API responses are cached in the `cache/` directory, with subdirectories for each importer, to minimize external calls.
43+### 1. Frontmatter
1944
20−## Developer Workflow
45+@frontmatter_rules [
46+ {
47+ "id": "position",
48+ "rule": "Must be at the very top of the file",
49+ "severity": "error"
50+ },
51+ {
52+ "id": "description",
53+ "rule": "Single sentence, clear purpose",
54+ "severity": "error"
55+ },
56+ {
57+ "id": "globs",
58+ "rule": "Array of relevant file patterns",
59+ "severity": "error"
60+ },
61+ {
62+ "id": "related_docs",
63+ "rule": "Optional array of related documentation files - MUST only reference existing files",
64+ "severity": "error"
65+ },
66+ {
67+ "id": "file_validation",
68+ "rule": "All referenced files must exist in the workspace",
69+ "severity": "error"
70+ }
71+]
2172
22−The project uses `Taskfile.yml` for task automation.
73+Example frontmatter:
74+```yaml
75+---
76+description: Guidelines for implementing feature X
77+globs: ["**/*.{ts,tsx}"]
78+related_docs: ["docs/architecture/feature-x.md"]
79+---
80+```
2381
24−- **Build & Test**: `task build` - This is the primary command for development. It automatically runs tests, lints the code, and compiles the binary to `build/hermes`.
25−- **Run Tests**: `task test` - Runs all tests and generates a coverage report in `coverage/`.
26−- **Lint Code**: `task lint` - Runs `golangci-lint`.
27−- **Run the CLI**: For development, use `go run . <command> [flags]`. For example: `go run . import goodreads -f path/to/export.csv`.
82+### 2. Metadata Annotations
2883
29−## Key Development Patterns
84+@annotations {
85+ "syntax": "@annotation_name JSON_content",
86+ "placement": "Before relevant sections",
87+ "format": "Valid JSON with proper indentation",
88+ "types": {
89+ "context": "Project and document context",
90+ "rules": "List of rules or requirements",
91+ "format": "Format specifications",
92+ "options": "Available options",
93+ "examples": "Implementation examples",
94+ "implementations": "Full implementation details",
95+ "related": "Related documentation or code"
96+ }
97+}
3098
31−- **Adding a New Importer**:
32− 1. Create a new package under `cmd/`.
33− 2. Mimic the structure of an existing importer (e.g., `cmd/goodreads`):
34− - `cmd.go`: Kong command definition.
35− - `parser.go`: Logic for parsing the source data file.
36− - `types.go`: Structs for the data models.
37− - `api.go` (or similar): Client for external APIs (e.g., OMDB, OpenLibrary).
38− - `cache.go`, `json.go`, `markdown.go`: Handlers for caching and output formats.
39− 3. Add the new command to `cmd/root.go`.
99+### 3. Content Structure
40100
41−- **Error Handling**:
42− - Return errors up the call stack.
43− - Wrap errors with context using `fmt.Errorf("...: %w", err)` to provide a clear trace.
44− - Use custom error types from `internal/errors` where applicable.
101+@content_rules {
102+ "headings": {
103+ "h1": "Single main title",
104+ "h2": "Major sections",
105+ "h3": "Subsections",
106+ "h4": "Detailed points"
107+ },
108+ "code_blocks": {
109+ "syntax": "Always specify language",
110+ "examples": "Include practical examples",
111+ "formatting": "Use proper indentation",
112+ "context": "Add explanatory comments"
113+ },
114+ "implementation_blocks": {
115+ "structure": "Group related implementations",
116+ "documentation": "Include inline documentation",
117+ "types": "Specify type information",
118+ "validation": "Include validation rules"
119+ }
120+}
45121
46−- **Utilities**:
47− - Always use helpers from `internal/` for common tasks like file writing (`fileutil`) and configuration (`config`).
48− - Contribute new, reusable logic back to the `internal/` packages.
122+## Best Practices
49123
50−- **Dependencies**:
51− - The project uses Go modules. Key libraries include `kong` for the CLI, `viper` for configuration, and `modernc.org/sqlite` for the database. Add new dependencies to `go.mod` only when necessary.
124+@best_practices {
125+ "organization": {
126+ "sections": "Use clear hierarchical structure",
127+ "annotations": "Place before relevant content",
128+ "examples": "Include practical examples"
129+ },
130+ "formatting": {
131+ "json": "Properly formatted, valid JSON",
132+ "markdown": "Clean, consistent spacing",
133+ "code": "Language-specific syntax highlighting"
134+ },
135+ "metadata": {
136+ "annotations": "Use semantic names",
137+ "context": "Provide clear scope",
138+ "versioning": "Include version information"
139+ },
140+ "implementation": {
141+ "examples": "Provide complete, working examples",
142+ "types": "Include type definitions",
143+ "validation": "Specify validation rules",
144+ "error_handling": "Document error cases"
145+ }
146+}
52147
53−## Gemini Agent Specific Notes
54−- Always use `task build` to build the project.
148+## Implementation Guidelines
149+
150+@implementation_rules {
151+ "code_examples": {
152+ "completeness": "Must be fully functional",
153+ "types": "Include all necessary type information",
154+ "imports": "Show all required imports",
155+ "context": "Provide setup and usage context"
156+ },
157+ "documentation": {
158+ "inline": "Add explanatory comments",
159+ "types": "Document type constraints",
160+ "errors": "Document error conditions",
161+ "usage": "Show usage patterns"
162+ }
163+}
164+
165+## Example Structure
166+
167+### Basic Example
168+```markdown
169+---
170+description: Example implementation of feature X
171+globs: ["src/features/**/*.ts"]
172+---
173+
174+# Feature X Implementation
175+
176+@context {
177+ "type": "implementation",
178+ "feature": "X",
179+ "version": "1.0.0"
180+}
181+
182+## Overview
183+[Feature description]
184+
185+## Implementation
186+
187+@implementation {
188+ "language": "typescript",
189+ "dependencies": ["dep1", "dep2"],
190+ "types": {
191+ "TypeX": "Description of TypeX"
192+ }
193+}
194+
195+```typescript
196+// Implementation code with types and validation
197+```
198+
199+## Usage Examples
200+[Usage examples with code]
201+```
202+
203+### Full Implementation Example
204+See the `examples` section in related .mdc files for complete implementation examples.
205+
206+## Common Patterns
207+
208+@patterns {
209+ "rules_section": {
210+ "format": "array of objects",
211+ "properties": ["id", "severity", "description"],
212+ "example": [
213+ {
214+ "id": "rule_name",
215+ "severity": "error",
216+ "description": "Clear description"
217+ }
218+ ]
219+ },
220+ "implementation_section": {
221+ "format": "object with implementation details",
222+ "required": [
223+ "language",
224+ "types",
225+ "validation"
226+ ],
227+ "example": {
228+ "language": "typescript",
229+ "types": {
230+ "Type1": "Description"
231+ },
232+ "validation": {
233+ "rule1": "Description"
234+ }
235+ }
236+ }
237+}
238+
239+## Examples
240+
241+### Minimal Valid MDC File
242+```markdown
243+---
244+description: A simple example MDC file
245+globs: ["**/*.example"]
246+---
247+
248+# Example Rules
249+
250+@context {
251+ "type": "example",
252+ "version": "1.0.0"
253+}
254+
255+## Section One
256+
257+@rules [
258+ {
259+ "id": "rule_one",
260+ "severity": "error",
261+ "description": "Description of rule one"
262+ }
263+]
264+```
265+
266+### Common Section Examples
267+
268+#### Rules Section
269+```markdown
270+@rules [
271+ {
272+ "id": "unique_identifier",
273+ "severity": "error|warning|info",
274+ "description": "Clear description of the rule"
275+ }
276+]
277+```
278+
279+#### Options Section
280+```markdown
281+@options {
282+ "option_name": "What this option does",
283+ "another_option": "Description of another option"
284+}
285+```
286+
287+#### Format Section
288+```markdown
289+@format {
290+ "base": "Template with {placeholders}",
291+ "options": ["array", "of", "options"],
292+ "paths": {
293+ "key": "value"
294+ }
295+}
296+```
297+
298+### Common Mistakes to Avoid
299+
300+@mistakes [
301+ {
302+ "id": "missing_frontmatter",
303+ "wrong": "Starting directly with content",
304+ "correct": "Include frontmatter at top",
305+ "reason": "Frontmatter is required for Cursor to properly parse the file"
306+ },
307+ {
308+ "id": "invalid_json",
309+ "wrong": "Malformed JSON in annotations",
310+ "correct": "Properly formatted JSON with quotes around keys",
311+ "reason": "Annotations must contain valid JSON for proper parsing"
312+ },
313+ {
314+ "id": "inconsistent_structure",
315+ "wrong": "Mixed levels of headings",
316+ "correct": "Clear hierarchical structure",
317+ "reason": "Consistent structure helps with readability and parsing"
318+ },
319+ {
320+ "id": "nonexistent_files",
321+ "wrong": "Referencing files that don't exist in the workspace",
322+ "correct": "Only reference files that exist and have been verified",
323+ "reason": "Prevents broken links and maintains documentation integrity"
324+ }
325+]
326+
327+## Validation
328+
329+@validation {
330+ "required": [
331+ "Frontmatter must be present and valid",
332+ "All JSON must be properly formatted",
333+ "Main title must be present",
334+ "At least one content section",
335+ "Complete implementation examples when relevant",
336+ "All referenced files must exist in the workspace"
337+ ],
338+ "recommended": [
339+ "Version information",
340+ "Last updated date",
341+ "Clear examples",
342+ "Proper code formatting",
343+ "Type definitions",
344+ "Validation rules",
345+ "Verify file existence before referencing"
346+ ]
347+}
348+
349+@version "1.1.0"
350+@last_updated "2024-03-19"
