# Code Style Guidelines ## Licensing & File Headers All files require SPDX headers: - **Go files**: `AGPL-3.0-or-later` - **Documentation/config** (`.md`, `.toml`): `CC0-1.0` - **Copyright**: `Amolith ` Include both lines as comments at the top of every new file. Annotate with `reuse annotate -c "Amolith " -l '' --exclude-year 'path/to/file'`. ## Go Code Style - Use `gofumpt` for formatting (`just fmt`) - Use `golangci-lint` for linting (`just lint`) - Use `staticcheck` for static analysis (`just staticcheck`) - Export types/functions with godoc comments starting with the name - Use provider interfaces to decouple packages (see `AreaProvider`, `GoalProvider`, `HabitProvider`) - Keep validation at two levels: tools layer (relationships, type checking) and lunatask layer (go-playground/validator tags) ## Configuration - Use TOML for configuration files, not JSON (per project philosophy) - Use IANA/Olson timezone format (`America/New_York`, not `EST`) - See `Configuration Guide.md` for complete config.toml structure and validation - See `Build & Development.md` and `Architecture & Design.md` for additional implementation context ## Implementation Rules ### Goal Validation in Task Operations When creating or updating tasks with a `goal_id`, the tools package validates that the goal belongs to the specified area. This prevents associating tasks with goals from different areas, which Lunatask may reject or handle incorrectly. ### Update vs Create Semantics `UpdateTask` reuses `CreateTaskRequest` type but has different semantics: - Only provided fields are updated (partial updates) - Empty strings for text fields (name, note, scheduled_on) clear existing values - Empty strings for enum fields (status, motivation) also clear values - The tools handler only sends fields present in MCP request arguments ### Empty Package Files `lunatask/notes.go`, `lunatask/people.go`, and `lunatask/timeline.go` exist but are empty. These are placeholders for future Lunatask API features. Don't remove them without checking if they're imported elsewhere. ### MCP Tool Workflow Dependencies Several tools must be called in specific order: 1. `list_areas_and_goals` → provides IDs for `create_task`/`update_task` 2. `get_timestamp` → provides formatted timestamps for task scheduling and habit tracking 3. `list_habits_and_activities` → provides IDs for `track_habit_activity` The MCP tool descriptions document these workflows, and the LLM system prompts (in README.md) reinforce the pattern. ## Build & Version - Always use `just build` or `just run`, never plain `go build` (version injection via ldflags) - Version is extracted from `git describe --long`