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
 27The project requires license headers (SPDX format) on all source files and uses REUSE for compliance checking.
 28
 29## Architecture Overview
 30
 31### Core Components
 32
 33**MCP Server Architecture**: The server follows a clean layered architecture:
 34
 35- `cmd/planning-mcp-server/main.go`: CLI entry point with Cobra, supports both STDIO and HTTP modes
 36- `internal/mcp/server.go`: MCP protocol wrapper that bridges MCP calls to planning operations
 37- `internal/planning/manager.go`: Core business logic with thread-safe in-memory storage
 38- `internal/planning/types.go`: Task and Goal type definitions with status management
 39- `internal/config/`: Configuration management with Viper, supports TOML files and env vars
 40
 41### Planning System Design
 42
 43**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.
 44
 45**Thread Safety**: The planning manager uses `sync.RWMutex` for concurrent access. All public methods properly lock/unlock.
 46
 47**Status System**: Tasks use emoji indicators with specific meanings:
 48
 49- `☐` pending
 50- `⟳` in_progress
 51- `☑` completed
 52- `☒` failed
 53- `⊗` cancelled
 54
 55**Task List Legend**: The `project_management__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.
 56
 57### MCP Tool Implementation
 58
 59The server exposes six MCP tools that map directly to planning manager methods:
 60
 61- `project_management__set_goal(title: string, description: string)`: Sets initial goal with title and description (both required). Returns error if goal already exists.
 62- `project_management__change_goal(title: string, description: string, reason: string)`: Changes existing goal (all parameters required). Only used when operator explicitly requests clearing/changing the goal.
 63- `project_management__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 `project_management__get_tasks`) when tasks already existed.
 64- `project_management__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.
 65- `project_management__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.
 66- `project_management__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.
 67
 68### Configuration System
 69
 70Uses a three-tier config system (defaults → file → environment variables):
 71
 72- Server mode: `stdio` (default) or `http`
 73- Planning limits: max tasks (100), max goal length (1000), max task length (500)
 74- Environment variables prefixed with `PLANNING_` (e.g., `PLANNING_SERVER_MODE`)
 75
 76## Development Guidelines
 77
 78### Code Patterns
 79
 80**Error Handling**: All functions return descriptive errors. MCP handlers convert errors to `CallToolResult` with `IsError: true`.
 81
 82**Validation**: Input validation happens at multiple layers - MCP parameter parsing, planning manager limits, and config validation.
 83
 84**Logging**: Uses structured logging (slog) throughout. All operations log at appropriate levels with contextual fields.
 85
 86### Testing Approach
 87
 88Testing is planned for future development. Priority areas for testing include:
 89
 90- Planning manager methods for concurrent access
 91- MCP request handling with mocked requests
 92- Configuration loading and validation edge cases
 93- Deterministic task ID generation
 94- Session management and persistence (when implemented)
 95
 96Note: Test files (`*_test.go`) will be added in future releases to ensure robust coverage of core functionality.
 97
 98### Key Dependencies
 99
100- `github.com/mark3labs/mcp-go`: MCP protocol implementation
101- `github.com/spf13/viper`: Configuration management
102- `github.com/spf13/cobra`: CLI framework
103- `github.com/charmbracelet/fang`: Enhanced CLI experience
104
105### Important Constraints
106
107**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.
108
109**Deterministic IDs**: Task IDs must remain consistent. Never change the ID generation algorithm without migration strategy.
110
111**MCP Compliance**: All tool responses must follow MCP schema. Responses include both success messages and full task lists where appropriate.
112
113**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.