| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 5 | 12 | 0% |
| Commands | 3 | 3 | 6 | 25% |
| Section tags | 2 | 1 | 5 | 25% |
What each file covers
Sections
0 shared · 5 only in A · 12 only in B- − Gemini Agent Guide for Hermes
- − Project Overview & Architecture
- − Developer Workflow
- − Key Development Patterns
- − Gemini Agent Specific Notes
- + Repository Guidelines
- + Managing AI-Generated Planning Documents
- + AI planning documents (ephemeral)
- + Important Rules
- + LLM Reference
- + Project Structure & Module Organization
- + Caching
- + Build, Test, and Development Commands
- + Coding Style & Naming Conventions
- + Testing Guidelines
- + Commit & Pull Request Guidelines
- + Landing the Plane (Session Completion)
Commands
3 shared · 3 only in A · 6 only in B- − go run . <command> [flags]
- − go run . import goodreads -f path/to/export.csv
- − go.mod
- + git pull --rebase
- + git push
- + git status
- + go test -race -coverprofile=coverage/coverage.out ./...
- + go run ./cmd/root.go --help
- + go test ./...
- task build
- task test
- task lint
Section tags
2 shared · 1 only in A · 5 only in B- − agent-behaviour
- + build
- + test
- + lint-format
- + git-pr
- + do-not
- code-style
- architecture
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 · AGENTS.md
@@ +1 @@
1# Repository Guidelines
2
3### Managing AI-Generated Planning Documents
4
5AI assistants often create planning and design documents during development:
6
7- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
8- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
9- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
10
11**Best Practice: Use a dedicated directory for these ephemeral files**
12
13**Recommended approach:**
14
15- Create a `history/` directory in the project root
16- Store ALL AI-generated planning/design docs in `history/`
17- Keep the repository root clean and focused on permanent project files
18- Only access `history/` when explicitly asked to review past planning
19
20**Example .gitignore entry (optional):**
21
22```
23# AI planning documents (ephemeral)
24history/
25```
26
27**Benefits:**
28
29- ✅ Clean repository root
30- ✅ Clear separation between ephemeral and permanent documentation
31- ✅ Easy to exclude from version control if desired
32- ✅ Preserves planning history for archeological research
33- ✅ Reduces noise when browsing the project
34
35### Important Rules
36
37- ✅ Store AI planning docs in `history/` directory
38- ✅ Always run `task build` before claiming work is done
39- ❌ Do NOT clutter repo root with planning documents
40
41### LLM Reference
42
43Need a quick tour of the shared helpers under `internal/`? Read `docs/internal_llm_reference.md` for package-by-package guidance before writing new utilities.
44
45## Project Structure & Module Organization
46
47- `main.go` wires the CLI and dispatches importer subcommands.
48- `cmd/` hosts CLI entrypoints per provider (e.g. `cmd/goodreads`, `cmd/steam`).
49- `internal/` contains shared services: `cache` for local stores, `datastore` for SQLite/JSON writers, `config` for settings.
50- `docs/` is the canonical reference; update it alongside behaviour changes and new flags.
51- Generated build and coverage artifacts live in `build/` and `coverage/`; sample exports under `exports/` and `json/` support local runs but keep large fixtures out of commits.
52
53## Caching
54
55- Hermes caches provider responses in `cache.db` (SQLite) in the repo root; it is safe to delete and is separate from `hermes.db`.
56- Default TTL is `720h` (30 days); override with `--cache-db-file`, `--cache-ttl`, or env vars `CACHE_DBFILE`/`CACHE_TTL`.
57- Tables are created automatically per provider (`omdb_cache`, `openlibrary_cache`, `steam_cache`, `letterboxd_cache`, `tmdb_cache`); entries past TTL refresh on next use and malformed entries are retried.
58- Warm caches by running the relevant importer once; invalidate selectively with `hermes cache invalidate tmdb|omdb|steam|letterboxd|openlibrary` or delete `cache.db` to clear everything.
59- Legacy JSON caches under `cache/` are deprecated and can be removed; negative TMDB results are intentionally not cached to allow future discoveries.
60
61## Build, Test, and Development Commands
62
63- `task build` runs lint, tests, and produces `build/hermes` with the current Git SHA embedded.
64- `task test` executes `go test -race -coverprofile=coverage/coverage.out ./...` and emits `coverage/coverage.html` for review.
65- `task lint` wraps `golangci-lint run ./...`; resolve findings before opening a PR.
66- `go run ./cmd/root.go --help` is a quick sanity check for new flags; swap in a provider folder (e.g. `./cmd/goodreads`) to exercise importer flows.
67
68## Coding Style & Naming Conventions
69
70- Format Go sources with `gofmt` or goimports integrations; Go defaults to tab-indentation, so avoid manual overrides.
71- Keep package names lowercase and singular; exported identifiers use UpperCamelCase, unexported ones use lowerCamelCase.
72- Prefer context-aware logging through the `humanlog` helpers and centralize config lookups in `internal/config` to keep importer packages lean.
73
74## Testing Guidelines
75
76- Co-locate `_test.go` files with the code under test; favour table-driven cases and `testify` assertions for clarity.
77- Run `task test` (or `go test ./...` when iterating) before pushing; inspect `coverage/coverage.html` for critical paths such as `internal/datastore` or importer pipelines.
78- Store lightweight fixtures under package-level `testdata/` directories and avoid reusing the large exports shipped at the repo root.
79
80## Commit & Pull Request Guidelines
81
82- Follow the existing Title-Case, imperative commit style (`Refactor caching`, `Add Steam importer config`) and keep each commit focused.
83- PRs should explain the motivation, list manual verification steps, and link issues; attach screenshots or sample output when behaviour is user-visible.
84- Before requesting review, ensure lint/tests pass, docs in `docs/` reflect the change, and configuration updates reference `config.yml` or `.env` expectations.
85
86## Landing the Plane (Session Completion)
87
88**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
89
90**MANDATORY WORKFLOW:**
91
921. **Note remaining work** - Capture anything that needs follow-up in the handoff
932. **Run quality gates** (if code changed) - Tests, linters, builds
943. **PUSH TO REMOTE** - This is MANDATORY:
95 ```bash
96 git pull --rebase
97 git push
98 git status # MUST show "up to date with origin"
99 ```
1004. **Clean up** - Clear stashes, prune remote branches
1015. **Verify** - All changes committed AND pushed
1026. **Hand off** - Provide context for next session
103
104**CRITICAL RULES:**
105- Work is NOT complete until `git push` succeeds
106- NEVER stop before pushing - that leaves work stranded locally
107- NEVER say "ready to push when you are" - YOU must push
108- If push fails, resolve and retry until it succeeds
109
@@ −1 +1 @@
1−# Gemini Agent Guide for Hermes
1+# Repository Guidelines
22
3−This guide provides essential information for developing in the Hermes codebase.
3+### Managing AI-Generated Planning Documents
44
5−## Project Overview & Architecture
5+AI assistants often create planning and design documents during development:
66
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.
7+- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
8+- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
9+- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
810
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.
11+**Best Practice: Use a dedicated directory for these ephemeral files**
1912
20−## Developer Workflow
13+**Recommended approach:**
2114
22−The project uses `Taskfile.yml` for task automation.
15+- Create a `history/` directory in the project root
16+- Store ALL AI-generated planning/design docs in `history/`
17+- Keep the repository root clean and focused on permanent project files
18+- Only access `history/` when explicitly asked to review past planning
2319
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`.
20+**Example .gitignore entry (optional):**
2821
29−## Key Development Patterns
22+```
23+# AI planning documents (ephemeral)
24+history/
25+```
3026
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`.
27+**Benefits:**
4028
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.
29+- ✅ Clean repository root
30+- ✅ Clear separation between ephemeral and permanent documentation
31+- ✅ Easy to exclude from version control if desired
32+- ✅ Preserves planning history for archeological research
33+- ✅ Reduces noise when browsing the project
4534
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.
35+### Important Rules
4936
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.
37+- ✅ Store AI planning docs in `history/` directory
38+- ✅ Always run `task build` before claiming work is done
39+- ❌ Do NOT clutter repo root with planning documents
5240
53−## Gemini Agent Specific Notes
54−- Always use `task build` to build the project.
41+### LLM Reference
42+
43+Need a quick tour of the shared helpers under `internal/`? Read `docs/internal_llm_reference.md` for package-by-package guidance before writing new utilities.
44+
45+## Project Structure & Module Organization
46+
47+- `main.go` wires the CLI and dispatches importer subcommands.
48+- `cmd/` hosts CLI entrypoints per provider (e.g. `cmd/goodreads`, `cmd/steam`).
49+- `internal/` contains shared services: `cache` for local stores, `datastore` for SQLite/JSON writers, `config` for settings.
50+- `docs/` is the canonical reference; update it alongside behaviour changes and new flags.
51+- Generated build and coverage artifacts live in `build/` and `coverage/`; sample exports under `exports/` and `json/` support local runs but keep large fixtures out of commits.
52+
53+## Caching
54+
55+- Hermes caches provider responses in `cache.db` (SQLite) in the repo root; it is safe to delete and is separate from `hermes.db`.
56+- Default TTL is `720h` (30 days); override with `--cache-db-file`, `--cache-ttl`, or env vars `CACHE_DBFILE`/`CACHE_TTL`.
57+- Tables are created automatically per provider (`omdb_cache`, `openlibrary_cache`, `steam_cache`, `letterboxd_cache`, `tmdb_cache`); entries past TTL refresh on next use and malformed entries are retried.
58+- Warm caches by running the relevant importer once; invalidate selectively with `hermes cache invalidate tmdb|omdb|steam|letterboxd|openlibrary` or delete `cache.db` to clear everything.
59+- Legacy JSON caches under `cache/` are deprecated and can be removed; negative TMDB results are intentionally not cached to allow future discoveries.
60+
61+## Build, Test, and Development Commands
62+
63+- `task build` runs lint, tests, and produces `build/hermes` with the current Git SHA embedded.
64+- `task test` executes `go test -race -coverprofile=coverage/coverage.out ./...` and emits `coverage/coverage.html` for review.
65+- `task lint` wraps `golangci-lint run ./...`; resolve findings before opening a PR.
66+- `go run ./cmd/root.go --help` is a quick sanity check for new flags; swap in a provider folder (e.g. `./cmd/goodreads`) to exercise importer flows.
67+
68+## Coding Style & Naming Conventions
69+
70+- Format Go sources with `gofmt` or goimports integrations; Go defaults to tab-indentation, so avoid manual overrides.
71+- Keep package names lowercase and singular; exported identifiers use UpperCamelCase, unexported ones use lowerCamelCase.
72+- Prefer context-aware logging through the `humanlog` helpers and centralize config lookups in `internal/config` to keep importer packages lean.
73+
74+## Testing Guidelines
75+
76+- Co-locate `_test.go` files with the code under test; favour table-driven cases and `testify` assertions for clarity.
77+- Run `task test` (or `go test ./...` when iterating) before pushing; inspect `coverage/coverage.html` for critical paths such as `internal/datastore` or importer pipelines.
78+- Store lightweight fixtures under package-level `testdata/` directories and avoid reusing the large exports shipped at the repo root.
79+
80+## Commit & Pull Request Guidelines
81+
82+- Follow the existing Title-Case, imperative commit style (`Refactor caching`, `Add Steam importer config`) and keep each commit focused.
83+- PRs should explain the motivation, list manual verification steps, and link issues; attach screenshots or sample output when behaviour is user-visible.
84+- Before requesting review, ensure lint/tests pass, docs in `docs/` reflect the change, and configuration updates reference `config.yml` or `.env` expectations.
85+
86+## Landing the Plane (Session Completion)
87+
88+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
89+
90+**MANDATORY WORKFLOW:**
91+
92+1. **Note remaining work** - Capture anything that needs follow-up in the handoff
93+2. **Run quality gates** (if code changed) - Tests, linters, builds
94+3. **PUSH TO REMOTE** - This is MANDATORY:
95+ ```bash
96+ git pull --rebase
97+ git push
98+ git status # MUST show "up to date with origin"
99+ ```
100+4. **Clean up** - Clear stashes, prune remote branches
101+5. **Verify** - All changes committed AND pushed
102+6. **Hand off** - Provide context for next session
103+
104+**CRITICAL RULES:**
105+- Work is NOT complete until `git push` succeeds
106+- NEVER stop before pushing - that leaves work stranded locally
107+- NEVER say "ready to push when you are" - YOU must push
108+- If push fails, resolve and retry until it succeeds
109+
