Code Style Guidelines.md

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 <amolith@secluded.site>

Include 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'.

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