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- `cmd/planning-mcp-server/main.go`: CLI entry point with Cobra, supports both STDIO and HTTP modes
 35- `internal/mcp/server.go`: MCP protocol wrapper that bridges MCP calls to planning operations
 36- `internal/planning/manager.go`: Core business logic with thread-safe in-memory storage
 37- `internal/config/`: Configuration management with Viper, supports TOML files and env vars
 38
 39### Planning System Design
 40
 41**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.
 42
 43**Thread Safety**: The planning manager uses `sync.RWMutex` for concurrent access. All public methods properly lock/unlock.
 44
 45**Status System**: Tasks use emoji indicators with specific meanings:
 46- `☐` pending
 47- `⟳` in_progress  
 48- `☑` completed
 49- `☒` failed
 50
 51**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 failed icon (☒) if there are actually failed tasks in the current list.
 52
 53### MCP Tool Implementation
 54
 55The server exposes four MCP tools that map directly to planning manager methods:
 56- `update_goal(goal: string)`: Sets overarching goal with length validation
 57- `add_tasks(tasks: []TaskInput)`: Batch task creation with duplicate detection. Encourages breaking tasks down into smallest units of work and regular progress tracking.
 58- `get_tasks()`: Returns markdown-formatted task list with legend and sorted by creation time. Should be called frequently to stay organized.
 59- `update_task_status(task_id: string, status: string)`: Updates task status and returns full list. Helps maintain planning workflow by tracking progress.
 60
 61### Configuration System
 62
 63Uses a three-tier config system (defaults → file → environment variables):
 64- Server mode: `stdio` (default) or `http`
 65- Planning limits: max tasks (100), max goal length (1000), max task length (500)
 66- Environment variables prefixed with `PLANNING_` (e.g., `PLANNING_SERVER_MODE`)
 67
 68## Development Guidelines
 69
 70### Code Patterns
 71
 72**Error Handling**: All functions return descriptive errors. MCP handlers convert errors to `CallToolResult` with `IsError: true`.
 73
 74**Validation**: Input validation happens at multiple layers - MCP parameter parsing, planning manager limits, and config validation.
 75
 76**Logging**: Uses structured logging (slog) throughout. All operations log at appropriate levels with contextual fields.
 77
 78### Testing Approach
 79
 80The project structure suggests unit testing at the package level. When adding tests:
 81- Test planning manager methods for concurrent access
 82- Mock MCP requests for server handler testing  
 83- Test configuration loading and validation edge cases
 84- Verify task ID generation is deterministic
 85
 86### Key Dependencies
 87
 88- `github.com/mark3labs/mcp-go`: MCP protocol implementation
 89- `github.com/spf13/viper`: Configuration management
 90- `github.com/spf13/cobra`: CLI framework
 91- `github.com/charmbracelet/fang`: Enhanced CLI experience
 92
 93### Important Constraints
 94
 95**Stateless Design**: No persistent storage - all data is in-memory. This is intentional for the planning use case.
 96
 97**Deterministic IDs**: Task IDs must remain consistent. Never change the ID generation algorithm without migration strategy.
 98
 99**MCP Compliance**: All tool responses must follow MCP schema. Responses include both success messages and full task lists where appropriate.
100
101**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.