| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 12 | 1 | 0% |
| Commands | 0 | 9 | 0 | 0% |
| Section tags | 3 | 4 | 1 | 38% |
What each file covers
Sections
0 shared · 12 only in A · 1 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)
- + Cursor Rules Location
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 · 1 only in B- − build
- − test
- − lint-format
- − git-pr
- + agent-behaviour
- code-style
- 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 · .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−# Repository Guidelines
1+---
2+description: Cursor Rules Location
3+globs: *.mdc
4+---
5+# Cursor Rules Location
26
3−### Managing AI-Generated Planning Documents
7+Rules for placing and organizing Cursor rule files in the repository.
48
5−AI assistants often create planning and design documents during development:
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−- 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
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"
1028
11−**Best Practice: Use a dedicated directory for these ephemeral files**
29+ - type: suggest
30+ message: |
31+ When creating Cursor rules:
1232
13−**Recommended approach:**
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+ ```
1440
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
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
1945
20−**Example .gitignore entry (optional):**
46+ 3. Directory structure:
47+ ```
48+ PROJECT_ROOT/
49+ ├── .cursor/
50+ │ └── rules/
51+ │ ├── your-rule-name.mdc
52+ │ └── ...
53+ └── ...
54+ ```
2155
22−```
23−# AI planning documents (ephemeral)
24−history/
25−```
56+ 4. Never place rule files:
57+ - In the project root
58+ - In subdirectories outside .cursor/rules
59+ - In any other location
2660
27−**Benefits:**
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
2867
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
68+ # Good: Rule file in correct location
69+ .cursor/rules/my-rule.mdc
70+ output: "Correctly placed Cursor rule file"
3471
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−
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−
72+metadata:
73+ priority: high
74+ version: 1.0
75+</rule>
