Cline rules

1# Humanlog Project Rules
2 
3## Shared Guidelines Reference
4 
5**This project follows the shared LLM assistant guidelines in [`llm-shared/`](../llm-shared/):**
6 
7- **[`llm-shared/project_tech_stack.md`](../llm-shared/project_tech_stack.md)**: Project management, validation, build/test/lint workflows, and universal conventions for all projects.
8- **[`llm-shared/languages/go.md`](../llm-shared/languages/go.md)**: Go-specific best practices, library choices, and code formatting/testing standards.
9- **[`llm-shared/utils/`](../llm-shared/utils/)**: Tools for code analysis and validation (e.g., `gofuncs`, `validate-docs`).
10- **[`llm-shared/templates/`](../llm-shared/templates/)**: Example `.gitignore`, `Taskfile.yml`, and CI workflow templates.
11 
12> **Always consult the above files for baseline rules. This file documents project-specific conventions and architectural notes for `humanlog`.**
13 
14---
15 
16## Project Management & Build Requirements
17 
18### Task Completion Criteria
19 
20- Task is not complete until `task build` succeeds, which includes:
21  - Running tests (`task test`)
22  - Linting the code (`task lint`)
23  - Building the project (if applicable)
24- Task is not complete until it has even basic unit tests, even if they are not comprehensive
25  - No need to mock external dependencies, just test the logic of the code
26- When working from a markdown checklist of tasks, check off the tasks as you complete them
27 
28### Build System Requirements
29 
30- Use `task build` over `go build` to ensure all tasks are run
31- All build artifacts should be placed in the `build/` directory
32- Build tasks must depend on test and lint tasks
33- Reference `llm-shared/templates/Taskfile.yml` for comprehensive task structure
34 
35### Project Validation
36 
37- Use the `validate-docs` tool to check if projects follow standard structure conventions:
38```bash
39  go run llm-shared/utils/validate-docs/validate-docs.go
40```
41 
42---
43 
44## Go-Specific Guidelines
45 
46### Code Formatting & Quality
47 
48- Always run `gofmt -w .` on Go code files after making changes
49- Use `go fmt ./...` and `go vet ./...` for linting
50- Functions that are easily unit-testable should have tests
51- Don't go for 100% test coverage, test the critical parts of the code
52 
53### Library Preferences
54 
55- Prefer using standard library packages when possible
56- Provide justification when adding new third-party dependencies
57- Keep dependencies updated
58- If SQLite is used, use "modernc.org/sqlite" as the library (no dependency on cgo)
59- Logging in applications run from cron: "log/slog" (standard library)
60- Logging in applications run from CLI: "fmt.Println" (standard library, use emojis for better UX)
61- Configuration management: "github.com/spf13/viper"
62- Command-line arguments: "github.com/alecthomas/kong" (only if the project requires complex CLI)
63 
64### Function Analysis
65 
66- When looking for functions, use the `gofuncs` tool to list all functions in a Go project:
67```bash
68  go run llm-shared/utils/gofuncs/gofuncs.go -dir /path/to/project
69```
70 
71---
72 
73## Project-Specific Rules for `humanlog`
74 
75### Overview & Architecture
76 
77- This package provides a human-readable formatter for Go's `log/slog` output.
78- Main components:
79  - `Handler` (`handler.go`): Implements `slog.Handler` with custom formatting.
80  - `Options` (`options.go`): Configures handler behavior.
81  - `NewHandler` (`humanlog.go`): Entry point for handler creation.
82- Example usage: `example/main.go`. Tests: `handler_test.go`.
83 
84### Developer Workflows
85 
86- **Build**: Use `task build` (or standard Go tools `go build`, `go install` if no Taskfile exists yet).
87- **Test**: `go test ./...` (see `handler_test.go`).
88- **Example**: `go run example/main.go` to see formatted log output.
89 
90### Project-Specific Conventions
91 
92- No global state; all config via `Options` or method params.
93- `NewHandler` panics if given a nil writer (enforced contract).
94- All exported types/functions must have doc comments.
95- Formatting helpers are unexported and colocated with usage.
96- Log messages are padded/truncated to a fixed width (see `messageWidth` in `handler.go`).
97- Color output for log levels unless `DisableColor` is set.
98 
99### Integration & Dependencies
100 
101- Only standard library and `log/slog` are used (following the minimal dependency principle).
102- Go module path: `github.com/lepinkainen/humanlog` (see `go.mod`).
103- When doing HTTP requests, use a custom user agent that includes the project name and version, e.g. `humanlog/1.0.0`
104 
105### Patterns & Examples
106 
107- See `example/main.go` for idiomatic usage patterns.
108- See `handler_test.go` for test structure and coverage.
109 
110---
111 
112## Development Workflow
113 
114### Code Analysis
115 
116- When analyzing large codebases that might exceed context limits, use the Gemini CLI:
117```bash
118  gemini -p "@src/main.go Explain this file's purpose and functionality"
119  gemini -p "@src/ Summarise the architecture of this codebase"
120  gemini -p "@src/ Is the project test coverage on par with industry standards?"
121```
122 
123### CI/CD Requirements
124 
125- Projects should have a basic GitHub Actions setup that uses the build-ci task
126- Use `llm-shared/templates/github/workflows/go-ci.yml` as a template
127- CI should run tests and linting on push and pull requests
128- Use `go test -tags=ci -cover -v ./...` for CI tests
129- Allow skipping tests with `//go:build !ci`
130 
131### Git Management
132 
133- Keep `.gitignore` up to date with Go-specific ignores
134- Use `llm-shared/templates/gitignore-go` as a reference
135- Ensure build artifacts and temporary files are not committed
136 
137---
138 
139## Templates & References
140 
141### Available Templates
142 
143- **Taskfile**: `llm-shared/templates/Taskfile.yml` - Comprehensive task management
144- **CI Workflow**: `llm-shared/templates/github/workflows/go-ci.yml` - GitHub Actions for Go
145- **Gitignore**: `llm-shared/templates/gitignore-go` - Go-specific ignore patterns
146- **Documentation**: `llm-shared/templates/README.md` and `llm-shared/templates/CHANGELOG.md`
147 
148### Project Structure
149 
150This project follows a simple Go library structure:
151 
152```
153humanlog/
154├── go.mod              # Go module definition
155├── *.go                # Main library files (handler.go, options.go, humanlog.go)
156├── *_test.go          # Test files
157├── example/           # Usage examples
158├── llm-shared/        # Shared development guidelines (submodule)
159├── docs/              # Project documentation (if needed)
160└── build/             # Build artifacts (when using Taskfile)
161```
162 
163---
164 
165_If any section is unclear or missing important project-specific details, please provide feedback or point to additional documentation to improve these rules._
166