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