| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 12 | 5 | 0% |
| Commands | 3 | 6 | 3 | 25% |
| Section tags | 2 | 5 | 1 | 25% |
What each file covers
Sections
0 shared · 12 only in A · 5 only in B- − 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)
- + Gemini Agent Guide for Hermes
- + Project Overview & Architecture
- + Developer Workflow
- + Key Development Patterns
- + Gemini Agent Specific Notes
Commands
3 shared · 6 only in A · 3 only in B- − git pull --rebase
- − git push
- − git status
- − go test -race -coverprofile=coverage/coverage.out ./...
- − go run ./cmd/root.go --help
- − go test ./...
- + go run . <command> [flags]
- + go run . import goodreads -f path/to/export.csv
- + go.mod
- task build
- task test
- task lint
Section tags
2 shared · 5 only in A · 1 only in B- − build
- − test
- − lint-format
- − git-pr
- − do-not
- + agent-behaviour
- code-style
- architecture
Line diff
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
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.
@@ −1 +1 @@
1−# Repository Guidelines
1+# Gemini Agent Guide for Hermes
22
3−### Managing AI-Generated Planning Documents
3+This guide provides essential information for developing in the Hermes codebase.
44
5−AI assistants often create planning and design documents during development:
5+## Project Overview & Architecture
66
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
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.
108
11−**Best Practice: Use a dedicated directory for these ephemeral files**
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.
1219
13−**Recommended approach:**
20+## Developer Workflow
1421
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
22+The project uses `Taskfile.yml` for task automation.
1923
20−**Example .gitignore entry (optional):**
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`.
2128
22−```
23−# AI planning documents (ephemeral)
24−history/
25−```
29+## Key Development Patterns
2630
27−**Benefits:**
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`.
2840
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
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.
3445
35−### Important Rules
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.
3649
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
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.
4052
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−
53+## Gemini Agent Specific Notes
54+- Always use `task build` to build the project.
