| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 5 | 1 | 0% |
| Commands | 0 | 6 | 0 | 0% |
| Section tags | 3 | 0 | 1 | 75% |
What each file covers
Sections
0 shared · 5 only in A · 1 only in B- − Gemini Agent Guide for Hermes
- − Project Overview & Architecture
- − Developer Workflow
- − Key Development Patterns
- − Gemini Agent Specific Notes
- + Cursor Rules Location
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/rules.mdc
@@ +1 @@
1---
2description: Cursor Rules Location
3globs: *.mdc
4---
5# Cursor Rules Location
6
7Rules for placing and organizing Cursor rule files in the repository.
8
9<rule>
10name: cursor_rules_location
11description: Standards for placing Cursor rule files in the correct directory
12filters:
13 # Match any .mdc files
14 - type: file_extension
15 pattern: "\\.mdc$"
16 # Match files that look like Cursor rules
17 - type: content
18 pattern: "(?s)<rule>.*?</rule>"
19 # Match file creation events
20 - type: event
21 pattern: "file_create"
22
23actions:
24 - type: reject
25 conditions:
26 - pattern: "^(?!\\.\\/\\.cursor\\/rules\\/.*\\.mdc$)"
27 message: "Cursor rule files (.mdc) must be placed in the .cursor/rules directory"
28
29 - type: suggest
30 message: |
31 When creating Cursor rules:
32
33 1. Always place rule files in PROJECT_ROOT/.cursor/rules/:
34 ```
35 .cursor/rules/
36 ├── your-rule-name.mdc
37 ├── another-rule.mdc
38 └── ...
39 ```
40
41 2. Follow the naming convention:
42 - Use kebab-case for filenames
43 - Always use .mdc extension
44 - Make names descriptive of the rule's purpose
45
46 3. Directory structure:
47 ```
48 PROJECT_ROOT/
49 ├── .cursor/
50 │ └── rules/
51 │ ├── your-rule-name.mdc
52 │ └── ...
53 └── ...
54 ```
55
56 4. Never place rule files:
57 - In the project root
58 - In subdirectories outside .cursor/rules
59 - In any other location
60
61examples:
62 - input: |
63 # Bad: Rule file in wrong location
64 rules/my-rule.mdc
65 my-rule.mdc
66 .rules/my-rule.mdc
67
68 # Good: Rule file in correct location
69 .cursor/rules/my-rule.mdc
70 output: "Correctly placed Cursor rule file"
71
72metadata:
73 priority: high
74 version: 1.0
75</rule>
@@ −1 +1 @@
1−# Gemini Agent Guide for Hermes
1+---
2+description: Cursor Rules Location
3+globs: *.mdc
4+---
5+# Cursor Rules Location
26
3−This guide provides essential information for developing in the Hermes codebase.
7+Rules for placing and organizing Cursor rule files in the repository.
48
5−## Project Overview & Architecture
9+<rule>
10+name: cursor_rules_location
11+description: Standards for placing Cursor rule files in the correct directory
12+filters:
13+ # Match any .mdc files
14+ - type: file_extension
15+ pattern: "\\.mdc$"
16+ # Match files that look like Cursor rules
17+ - type: content
18+ pattern: "(?s)<rule>.*?</rule>"
19+ # Match file creation events
20+ - type: event
21+ pattern: "file_create"
622
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.
23+actions:
24+ - type: reject
25+ conditions:
26+ - pattern: "^(?!\\.\\/\\.cursor\\/rules\\/.*\\.mdc$)"
27+ message: "Cursor rule files (.mdc) must be placed in the .cursor/rules directory"
828
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.
29+ - type: suggest
30+ message: |
31+ When creating Cursor rules:
1932
20−## Developer Workflow
33+ 1. Always place rule files in PROJECT_ROOT/.cursor/rules/:
34+ ```
35+ .cursor/rules/
36+ ├── your-rule-name.mdc
37+ ├── another-rule.mdc
38+ └── ...
39+ ```
2140
22−The project uses `Taskfile.yml` for task automation.
41+ 2. Follow the naming convention:
42+ - Use kebab-case for filenames
43+ - Always use .mdc extension
44+ - Make names descriptive of the rule's purpose
2345
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`.
46+ 3. Directory structure:
47+ ```
48+ PROJECT_ROOT/
49+ ├── .cursor/
50+ │ └── rules/
51+ │ ├── your-rule-name.mdc
52+ │ └── ...
53+ └── ...
54+ ```
2855
29−## Key Development Patterns
56+ 4. Never place rule files:
57+ - In the project root
58+ - In subdirectories outside .cursor/rules
59+ - In any other location
3060
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`.
61+examples:
62+ - input: |
63+ # Bad: Rule file in wrong location
64+ rules/my-rule.mdc
65+ my-rule.mdc
66+ .rules/my-rule.mdc
4067
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.
68+ # Good: Rule file in correct location
69+ .cursor/rules/my-rule.mdc
70+ output: "Correctly placed Cursor rule file"
4571
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.
72+metadata:
73+ priority: high
74+ version: 1.0
75+</rule>
