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 seven 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 them 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- **`modify_task`**: Modify the title and/or description of a task. ID and at least one of title/description are required. When one or the other is omitted, that field will not be modified.
 21- **`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.
 22
 23## Development Commands
 24
 25This project uses `just` as the build tool. Essential commands:
 26
 27```bash
 28# Full development workflow (default)
 29just
 30
 31# Individual commands
 32just fmt          # Format Go code with gofumpt
 33just lint         # Run golangci-lint
 34just staticcheck  # Static analysis
 35just test         # Run tests with go test -v ./...
 36just vuln         # Check for vulnerabilities with govulncheck
 37just reuse        # Check license/copyright headers
 38
 39# Building and running
 40just build        # Build binary
 41just run          # Run server directly
 42just install      # Install to GOPATH/bin
 43
 44# Running specific tests
 45go test -v -run TestName ./internal/mcp  # Run single test by name
 46go test -v ./internal/planning           # Run tests for specific package
 47
 48# Maintenance
 49go mod tidy       # Clean up unused dependencies
 50```
 51
 52The project requires license headers (SPDX format) on all source files and uses REUSE for compliance checking.
 53
 54## Architecture Overview
 55
 56### Core Components
 57
 58**MCP Server Architecture**: The server follows a clean layered architecture:
 59
 60- `cmd/planning-mcp-server/main.go`: CLI entry point with Cobra, supports both STDIO and HTTP modes
 61- `internal/mcp/server.go`: MCP protocol wrapper that bridges MCP calls to planning operations
 62- `internal/planning/manager.go`: Core business logic with thread-safe in-memory storage
 63- `internal/planning/types.go`: Task and Goal type definitions with status management
 64- `internal/config/`: Configuration management with Viper, supports TOML files and env vars
 65
 66### Planning System Design
 67
 68**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.
 69
 70**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.
 71
 72**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.
 73
 74**Status System**: Tasks use emoji indicators with specific meanings:
 75
 76- `☐` pending
 77- `⟳` in_progress
 78- `☑` completed
 79- `☒` failed
 80- `⊗` cancelled
 81
 82**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.
 83
 84The 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.
 85
 86### MCP Tool Implementation
 87
 88The server exposes seven MCP tools that map directly to planning manager methods:
 89
 90- `set_goal(title: string, description: string)`: Sets initial goal with title and description (both required). Returns error if goal already exists.
 91- `change_goal(title: string, description: string, reason: string)`: Changes existing goal (all parameters required). Only used when operator explicitly requests clearing/changing the goal.
 92- `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.
 93- `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.
 94- `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.
 95- `modify_task(task_id: string, title?: string, description?: string)`: Modifies the title and/or description of a task. ID and at least one of title/description are required. When one or the other is omitted, that field will not be modified. Regenerates the task ID based on new content and returns the updated task list.
 96- `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.
 97
 98### Configuration System
 99
100Uses a three-tier config system (defaults → file → environment variables):
101
102- Server mode: `stdio` (default) or `http`
103- Planning limits: max tasks (100), max goal length (1000), max task length (500)
104- Environment variables prefixed with `PLANNING_` (e.g., `PLANNING_SERVER_MODE`)
105- Config file search paths (in order): current directory, `$HOME/.config/planning-mcp-server`, `/etc/planning-mcp-server`
106- Config file name: `planning-mcp-server.toml`
107
108## Development Guidelines
109
110### Code Patterns
111
112**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.
113
114**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.
115
116**Validation**: Input validation happens at multiple layers - MCP parameter parsing, planning manager limits, and config validation.
117
118**Logging**: Uses structured logging (slog) throughout. All operations log at appropriate levels with contextual fields.
119
120### Testing Approach
121
122Testing is planned for future development. Priority areas for testing include:
123
124- Planning manager methods for concurrent access
125- MCP request handling with mocked requests
126- Configuration loading and validation edge cases
127- Deterministic task ID generation
128- Session management and persistence (when implemented)
129
130Note: Test files (`*_test.go`) will be added in future releases to ensure robust coverage of core functionality.
131
132### Key Dependencies
133
134- `github.com/mark3labs/mcp-go`: MCP protocol implementation
135- `github.com/spf13/viper`: Configuration management
136- `github.com/spf13/cobra`: CLI framework
137- `github.com/charmbracelet/fang`: Enhanced CLI experience
138
139### Important Constraints
140
141**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.
142
143The server uses Unicode characters for statuses because they each count as one token, while Markdown checkboxes and other representations take up multiple tokens.
144
145**Deterministic IDs**: Task IDs must remain consistent. Never change the ID generation algorithm without migration strategy.
146
147**MCP Compliance**: All tool responses must follow MCP schema. Responses include both success messages and full task lists where appropriate.
148
149**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.