1<!--
  2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
  3
  4SPDX-License-Identifier: CC0-1.0
  5-->
  6
  7# AGENTS.md
  8
  9This file provides guidance to AI coding assistants when working with code in this repository.
 10
 11## planning-mcp-server capabilities
 12
 13The server provides six essential planning tools:
 14
 15- **`set_goal`**: Set the initial goal for your planning session (title and description required). Returns error if goal already exists.
 16- **`change_goal`**: Change an existing goal with a required reason for the change. Only used when operator explicitly requests clearing/changing the goal.
 17- **`add_tasks`**: Add one or more tasks to work on. Break tasks down into the smallest units of work possible and track progress. Each task requires a title (and optional description).
 18- **`get_tasks`**: Get task list with optional status filtering and indicators. Call frequently to stay organized.
 19- **`update_task_statuses`**: Update the status of one or more tasks. Maintain your planning workflow by updating statuses regularly.
 20- **`delete_tasks`**: Delete one or more tasks by their IDs and return the updated task list. Only use if the operator explicitly requests clearing the board.
 21
 22## Development Commands
 23
 24This project uses `just` as the build tool. Essential commands:
 25
 26```bash
 27# Full development workflow (default)
 28just
 29
 30# Individual commands
 31just fmt          # Format Go code with gofumpt
 32just lint         # Run golangci-lint
 33just staticcheck  # Static analysis
 34just test         # Run tests with go test -v ./...
 35just vuln         # Check for vulnerabilities with govulncheck
 36just reuse        # Check license/copyright headers
 37
 38# Building and running
 39just build        # Build binary
 40just run          # Run server directly
 41just install      # Install to GOPATH/bin
 42
 43# Running specific tests
 44go test -v -run TestName ./internal/mcp  # Run single test by name
 45go test -v ./internal/planning           # Run tests for specific package
 46
 47# Maintenance
 48go mod tidy       # Clean up unused dependencies
 49```
 50
 51The project requires license headers (SPDX format) on all source files and uses REUSE for compliance checking.
 52
 53## Architecture Overview
 54
 55### Core Components
 56
 57**MCP Server Architecture**: The server follows a clean layered architecture:
 58
 59- `cmd/planning-mcp-server/main.go`: CLI entry point with Cobra, supports both STDIO and HTTP modes
 60- `internal/mcp/server.go`: MCP protocol wrapper that bridges MCP calls to planning operations
 61- `internal/planning/manager.go`: Core business logic with thread-safe in-memory storage
 62- `internal/planning/types.go`: Task and Goal type definitions with status management
 63- `internal/config/`: Configuration management with Viper, supports TOML files and env vars
 64
 65### Planning System Design
 66
 67**Task Management**: Tasks use deterministic IDs generated via SHA256 hash of `title:description`, ensuring consistent IDs across sessions without persistence. This is critical - task IDs are not user-provided but generated automatically. The ID is exactly 8 hex characters (first 4 bytes of SHA256 hash). Duplicate task detection happens silently - if a task with the same ID already exists, it's skipped with a warning log but no error is returned.
 68
 69**Thread Safety**: The planning manager uses `sync.RWMutex` for concurrent access. All public methods properly lock/unlock. The `UpdateTasks` method implements an atomic update pattern - it validates all task IDs exist before applying any updates, ensuring all-or-nothing semantics.
 70
 71**Task List Ordering**: Tasks are always displayed sorted by creation time (oldest first) for consistent output across operations. This ordering is maintained even when filtering by status.
 72
 73**Status System**: Tasks use emoji indicators with specific meanings:
 74
 75- `☐` pending
 76- `⟳` in_progress
 77- `☑` completed
 78- `☒` failed
 79- `⊗` cancelled
 80
 81**Task List Legend**: The `get_tasks()` method includes a legend showing status indicators. The legend format is "Legend: ☐ pending ⟳ in progress ☑ completed" and only includes the cancelled icon (⊗) and failed icon (☒) if there are actually cancelled or failed tasks in the current list.
 82
 83The server uses in-memory storage only. All goals and tasks are lost when the server restarts. Session management and persistence are planned for future releases.
 84
 85### MCP Tool Implementation
 86
 87The server exposes six MCP tools that map directly to planning manager methods:
 88
 89- `set_goal(title: string, description: string)`: Sets initial goal with title and description (both required). Returns error if goal already exists.
 90- `change_goal(title: string, description: string, reason: string)`: Changes existing goal (all parameters required). Only used when operator explicitly requests clearing/changing the goal.
 91- `add_tasks(tasks: []TaskInput)`: Batch task creation with duplicate detection. Each task requires `title` (required) and `description` (optional). Encourages breaking tasks down into smallest units of work and regular progress tracking. Output behavior depends on existing tasks: shows verbose instructions + task list when no tasks existed previously, shows brief task list (like `get_tasks`) when tasks already existed.
 92- `get_tasks(status: string)`: Returns markdown-formatted task list with optional status filter (all, pending, in_progress, completed, cancelled, failed). Default is "all". Should be called frequently to stay organized.
 93- `update_task_statuses(tasks: []TaskUpdate)`: Updates status of one or more tasks and returns full list. Never cancels tasks autonomously - marks as failed on errors and asks operator for guidance.
 94- `delete_tasks(task_ids: []string)`: Deletes one or more tasks by their IDs. Only used when operator explicitly requests clearing the board. Otherwise, tasks should be marked as cancelled/failed. Returns the resulting task list.
 95
 96### Configuration System
 97
 98Uses a three-tier config system (defaults → file → environment variables):
 99
100- Server mode: `stdio` (default) or `http`
101- Planning limits: max tasks (100), max goal length (1000), max task length (500)
102- Environment variables prefixed with `PLANNING_` (e.g., `PLANNING_SERVER_MODE`)
103- Config file search paths (in order): current directory, `$HOME/.config/planning-mcp-server`, `/etc/planning-mcp-server`
104- Config file name: `planning-mcp-server.toml`
105
106## Development Guidelines
107
108### Code Patterns
109
110**Error Handling**: All functions return descriptive errors. MCP handlers convert errors to `CallToolResult` with `IsError: true`. The `internal/mcp/helpers.go` provides standardized helper functions (`createErrorResult`, `createSuccessResult`) for consistent MCP responses.
111
112**Goal Formatting**: Goals are internally stored as a single text field combining title and description in the format `"title: description"`. The `formatGoalText` helper ensures consistent formatting across the codebase.
113
114**Validation**: Input validation happens at multiple layers - MCP parameter parsing, planning manager limits, and config validation.
115
116**Logging**: Uses structured logging (slog) throughout. All operations log at appropriate levels with contextual fields.
117
118### Testing Approach
119
120Testing is planned for future development. Priority areas for testing include:
121
122- Planning manager methods for concurrent access
123- MCP request handling with mocked requests
124- Configuration loading and validation edge cases
125- Deterministic task ID generation
126- Session management and persistence (when implemented)
127
128Note: Test files (`*_test.go`) will be added in future releases to ensure robust coverage of core functionality.
129
130### Key Dependencies
131
132- `github.com/mark3labs/mcp-go`: MCP protocol implementation
133- `github.com/spf13/viper`: Configuration management
134- `github.com/spf13/cobra`: CLI framework
135- `github.com/charmbracelet/fang`: Enhanced CLI experience
136
137### Important Constraints
138
139**Current Storage Model**: In-memory storage only - all data is lost on server restart. Session management and persistence are planned for future releases to enable task continuity across sessions.
140
141The server uses Unicode characters for statuses because they each count as one token, while Markdown checkboxes and other representations take up multiple tokens.
142
143**Deterministic IDs**: Task IDs must remain consistent. Never change the ID generation algorithm without migration strategy.
144
145**MCP Compliance**: All tool responses must follow MCP schema. Responses include both success messages and full task lists where appropriate.
146
147**SPDX Licensing**: All new files require SPDX headers. Use `SPDX-FileCopyrightText: Amolith <amolith@secluded.site>` and `SPDX-License-Identifier: AGPL-3.0-or-later` for source files.