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