1<!--
 2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
 3
 4SPDX-License-Identifier: CC0-1.0
 5-->
 6
 7# Code Style Guidelines
 8
 9## Licensing & File Headers
10
11All files require SPDX headers:
12
13- **Go files**: `AGPL-3.0-or-later`
14- **Documentation/config** (`.md`, `.toml`): `CC0-1.0`
15- **Copyright**: `Amolith <amolith@secluded.site>`
16
17Include both lines as comments at the top of every new file. Annotate with `reuse annotate -c "Amolith <amolith@secluded.site>" -l '<license_id>' --exclude-year 'path/to/file'`.
18
19## Go Code Style
20
21- Use `gofumpt` for formatting (`just fmt`)
22- Use `golangci-lint` for linting (`just lint`)
23- Use `staticcheck` for static analysis (`just staticcheck`)
24- Export types/functions with godoc comments starting with the name
25- Use provider interfaces to decouple packages (see `AreaProvider`, `GoalProvider`, `HabitProvider`)
26- Keep validation at two levels: tools layer (relationships, type checking) and lunatask layer (go-playground/validator tags)
27
28## Configuration
29
30- Use TOML for configuration files, not JSON (per project philosophy)
31- Use IANA/Olson timezone format (`America/New_York`, not `EST`)
32- See `Configuration Guide.md` for complete config.toml structure and validation
33- See `Build & Development.md` and `Architecture & Design.md` for additional implementation context
34
35## Implementation Rules
36
37### Goal Validation in Task Operations
38
39When 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.
40
41### Update vs Create Semantics
42
43`UpdateTask` reuses `CreateTaskRequest` type but has different semantics:
44- Only provided fields are updated (partial updates)
45- Empty strings for text fields (name, note, scheduled_on) clear existing values
46- Empty strings for enum fields (status, motivation) also clear values
47- The tools handler only sends fields present in MCP request arguments
48
49### Empty Package Files
50
51`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.
52
53### MCP Tool Workflow Dependencies
54
55Several tools must be called in specific order:
561. `list_areas_and_goals` → provides IDs for `create_task`/`update_task`
572. `get_timestamp` → provides formatted timestamps for task scheduling and habit tracking
583. `list_habits_and_activities` → provides IDs for `track_habit_activity`
59
60The MCP tool descriptions document these workflows, and the LLM system prompts (in README.md) reinforce the pattern.
61
62## Build & Version
63
64- Always use `just build` or `just run`, never plain `go build` (version injection via ldflags)
65- Version is extracted from `git describe --long`