| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 11 | 13 | 4% |
| Commands | 0 | 9 | 0 | 0% |
| Section tags | 3 | 4 | 2 | 33% |
What each file covers
Sections
1 shared · 11 only in A · 13 only in B- − Repository Guidelines
- − Managing AI-Generated Planning Documents
- − AI planning documents (ephemeral)
- − Important Rules
- − LLM Reference
- − Project Structure & Module Organization
- − Build, Test, and Development Commands
- − Coding Style & Naming Conventions
- − Testing Guidelines
- − Commit & Pull Request Guidelines
- − Landing the Plane (Session Completion)
- + Hermes Project Rules
- + Tech Stack Reference
- + Project-Specific Guidelines
- + Code Structure
- + Implementation Requirements
- + Error Handling
- + Configuration Management
- + Logging
- + Output Formats & Handling
- + External API Interaction
- + Testing
- + Utilities
- + Documentation
- Caching
Commands
0 shared · 9 only in A · 0 only in B- − git pull --rebase
- − git push
- − git status
- − task build
- − task test
- − go test -race -coverprofile=coverage/coverage.out ./...
- − task lint
- − go run ./cmd/root.go --help
- − go test ./...
Section tags
3 shared · 4 only in A · 2 only in B- − build
- − lint-format
- − code-style
- − git-pr
- + api
- + docs
- test
- architecture
- do-not
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 · .clinerules/project-rules.md
@@ +1 @@
1# Hermes Project Rules
2
3## Tech Stack Reference
4
5See `llm-shared/project_tech_stack.md` for core technology choices, build system configuration, and library preferences.
6
7## Project-Specific Guidelines
8
9- **Unit Tests:** Write basic unit tests for new functionality. Always check the tests pass after finishing changes.
10- **Purpose:** See README.md for project definition
11
12## Code Structure
13
14- All import processors go under the `cmd/` directory
15- The internal/ directory contains common utility functions, use it when possible. Add to it when necessary.
16- Each processor has its own subdirectory and Go package
17
18## Implementation Requirements
19
20- Maintain consistent Go style and idiomatic patterns
21- Follow the existing architectural patterns
22- Each data source processor should be implemented as a separate command
23
24## Error Handling
25
26- Use standard Go error handling (`errors.New`, `fmt.Errorf`). Return errors up the call stack for handling by Cobra's `RunE`.
27- Wrap errors with context where appropriate to aid debugging (e.g., `fmt.Errorf("failed to process item %s: %w", itemID, err)`).
28- Utilize custom error types from `internal/errors` for specific conditions like API rate limits when applicable.
29- Log significant errors within the command logic but generally return them to let the top level (`main.go` or Cobra) handle exit codes.
30
31## Configuration Management
32
33- Configuration is managed via Viper, reading `config.yaml` by default.
34- Global settings (like output directories, overwrite flag) are defined in `root.go` and accessed via `internal/config` or Viper directly.
35- Command-specific configuration (e.g., input file paths, API keys) should use keys namespaced by the command name in `config.yaml` (e.g., `goodreads.csvfile`, `steam.apikey`).
36- Prioritize command-line flags over config file values when both are provided.
37
38## Logging
39
40- Log informational messages about progress (e.g., starting import, items processed) at `InfoLevel`.
41- Use `DebugLevel` for verbose information useful for debugging (e.g., detailed API request/response info, cache hits/misses).
42- Use `WarnLevel` for recoverable issues (e.g., skipping an item due to missing data but continuing the import).
43- Use `ErrorLevel` for significant problems encountered within functions, often just before returning an error.
44
45## Caching
46
47- Use the `cache/` directory for caching external API responses.
48- Organize cache files into subdirectories named after the data source (e.g., `cache/goodreads/`, `cache/omdb/`).
49- Implement caching logic within the specific command package (e.g., `cmd/goodreads/cache.go`).
50- Respect API rate limits using appropriate delays or by handling specific rate limit errors.
51
52## Output Formats & Handling
53
54- Default output directories (`markdown/`, `json/`) are set in `root.go` and configurable via `config.yaml`.
55- Commands should allow specifying subdirectories for their output via flags/config (e.g., `markdown/goodreads/`).
56- Use `internal/fileutil` for writing Markdown and JSON files, ensuring consistent formatting and handling the `overwrite` flag logic.
57- Follow existing patterns for Markdown frontmatter and JSON structure for each data type.
58
59## External API Interaction
60
61- Implement API client logic within the relevant command package (e.g., `cmd/goodreads/openlibrary.go`).
62- Respect API rate limits using appropriate delays (`time.Sleep`) or by handling specific rate limit errors.
63- Utilize caching (`cache/`) to minimize redundant API calls.
64- Handle common API errors gracefully (e.g., log a warning for 404 Not Found, retry or fail on persistent errors).
65
66## Testing
67
68- Write unit tests for parsing logic, API interaction (using mocks/stubs), and output generation.
69- Place tests in `_test.go` files within the same package.
70- Use the `testdata/` subdirectory within each command package for input fixtures and expected output files.
71- Employ table-driven tests for validating multiple input cases efficiently.
72
73## Utilities
74
75- Use shared utility functions from `internal/` packages (e.g., `cmdutil` for command setup, `fileutil` for file operations).
76- Contribute reusable logic back to these `internal/` packages when appropriate.
77
78## Documentation
79
80- Write Go doc comments for all exported functions, types, and constants.
81- Keep command help messages (`Short`, `Long` fields in `cobra.Command`) clear and up-to-date.
82- Update `README.md` and any relevant files in `docs/` when adding new commands or changing functionality significantly.
83
@@ −1 +1 @@
1−# Repository Guidelines
1+# Hermes Project Rules
22
3−### Managing AI-Generated Planning Documents
3+## Tech Stack Reference
44
5−AI assistants often create planning and design documents during development:
5+See `llm-shared/project_tech_stack.md` for core technology choices, build system configuration, and library preferences.
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+## Project-Specific Guidelines
108
11−**Best Practice: Use a dedicated directory for these ephemeral files**
9+- **Unit Tests:** Write basic unit tests for new functionality. Always check the tests pass after finishing changes.
10+- **Purpose:** See README.md for project definition
1211
13−**Recommended approach:**
12+## Code Structure
1413
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
14+- All import processors go under the `cmd/` directory
15+- The internal/ directory contains common utility functions, use it when possible. Add to it when necessary.
16+- Each processor has its own subdirectory and Go package
1917
20−**Example .gitignore entry (optional):**
18+## Implementation Requirements
2119
22−```
23−# AI planning documents (ephemeral)
24−history/
25−```
20+- Maintain consistent Go style and idiomatic patterns
21+- Follow the existing architectural patterns
22+- Each data source processor should be implemented as a separate command
2623
27−**Benefits:**
24+## Error Handling
2825
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
26+- Use standard Go error handling (`errors.New`, `fmt.Errorf`). Return errors up the call stack for handling by Cobra's `RunE`.
27+- Wrap errors with context where appropriate to aid debugging (e.g., `fmt.Errorf("failed to process item %s: %w", itemID, err)`).
28+- Utilize custom error types from `internal/errors` for specific conditions like API rate limits when applicable.
29+- Log significant errors within the command logic but generally return them to let the top level (`main.go` or Cobra) handle exit codes.
3430
35−### Important Rules
31+## Configuration Management
3632
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
33+- Configuration is managed via Viper, reading `config.yaml` by default.
34+- Global settings (like output directories, overwrite flag) are defined in `root.go` and accessed via `internal/config` or Viper directly.
35+- Command-specific configuration (e.g., input file paths, API keys) should use keys namespaced by the command name in `config.yaml` (e.g., `goodreads.csvfile`, `steam.apikey`).
36+- Prioritize command-line flags over config file values when both are provided.
4037
41−### LLM Reference
38+## Logging
4239
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.
40+- Log informational messages about progress (e.g., starting import, items processed) at `InfoLevel`.
41+- Use `DebugLevel` for verbose information useful for debugging (e.g., detailed API request/response info, cache hits/misses).
42+- Use `WarnLevel` for recoverable issues (e.g., skipping an item due to missing data but continuing the import).
43+- Use `ErrorLevel` for significant problems encountered within functions, often just before returning an error.
4444
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−
5345 ## Caching
5446
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.
47+- Use the `cache/` directory for caching external API responses.
48+- Organize cache files into subdirectories named after the data source (e.g., `cache/goodreads/`, `cache/omdb/`).
49+- Implement caching logic within the specific command package (e.g., `cmd/goodreads/cache.go`).
50+- Respect API rate limits using appropriate delays or by handling specific rate limit errors.
6051
61−## Build, Test, and Development Commands
52+## Output Formats & Handling
6253
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.
54+- Default output directories (`markdown/`, `json/`) are set in `root.go` and configurable via `config.yaml`.
55+- Commands should allow specifying subdirectories for their output via flags/config (e.g., `markdown/goodreads/`).
56+- Use `internal/fileutil` for writing Markdown and JSON files, ensuring consistent formatting and handling the `overwrite` flag logic.
57+- Follow existing patterns for Markdown frontmatter and JSON structure for each data type.
6758
68−## Coding Style & Naming Conventions
59+## External API Interaction
6960
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.
61+- Implement API client logic within the relevant command package (e.g., `cmd/goodreads/openlibrary.go`).
62+- Respect API rate limits using appropriate delays (`time.Sleep`) or by handling specific rate limit errors.
63+- Utilize caching (`cache/`) to minimize redundant API calls.
64+- Handle common API errors gracefully (e.g., log a warning for 404 Not Found, retry or fail on persistent errors).
7365
74−## Testing Guidelines
66+## Testing
7567
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.
68+- Write unit tests for parsing logic, API interaction (using mocks/stubs), and output generation.
69+- Place tests in `_test.go` files within the same package.
70+- Use the `testdata/` subdirectory within each command package for input fixtures and expected output files.
71+- Employ table-driven tests for validating multiple input cases efficiently.
7972
80−## Commit & Pull Request Guidelines
73+## Utilities
8174
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.
75+- Use shared utility functions from `internal/` packages (e.g., `cmdutil` for command setup, `fileutil` for file operations).
76+- Contribute reusable logic back to these `internal/` packages when appropriate.
8577
86−## Landing the Plane (Session Completion)
78+## Documentation
8779
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
80+- Write Go doc comments for all exported functions, types, and constants.
81+- Keep command help messages (`Short`, `Long` fields in `cobra.Command`) clear and up-to-date.
82+- Update `README.md` and any relevant files in `docs/` when adding new commands or changing functionality significantly.
10983
