AGENTS.md

AGENTS.md

This file provides guidance to AI coding assistants when working with code in this repository.

Development Commands

This project uses just as the build tool. Essential commands:

# Full development workflow (default)
just

# Individual commands
just fmt          # Format Go code with gofumpt
just lint         # Run golangci-lint
just staticcheck  # Static analysis
just test         # Run tests with go test -v ./...
just vuln         # Check for vulnerabilities with govulncheck
just reuse        # Check license/copyright headers

# Building and running
just build        # Build binary
just run          # Run server directly
just install      # Install to GOPATH/bin

The project requires license headers (SPDX format) on all source files and uses REUSE for compliance checking.

Architecture Overview

Core Components

MCP Server Architecture: The server follows a clean layered architecture:

  • cmd/planning-mcp-server/main.go: CLI entry point with Cobra, supports both STDIO and HTTP modes
  • internal/mcp/server.go: MCP protocol wrapper that bridges MCP calls to planning operations
  • internal/planning/manager.go: Core business logic with thread-safe in-memory storage
  • internal/config/: Configuration management with Viper, supports TOML files and env vars

Planning System Design

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.

Thread Safety: The planning manager uses sync.RWMutex for concurrent access. All public methods properly lock/unlock.

Status System: Tasks use emoji indicators with specific meanings:

  • ☐ pending
  • ⟳ in_progress
  • ☑ completed
  • ☒ failed

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.

MCP Tool Implementation

The server exposes four MCP tools that map directly to planning manager methods:

  • update_goal(goal: string): Sets overarching goal with length validation
  • add_tasks(tasks: []TaskInput): Batch task creation with duplicate detection. 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.
  • get_tasks(): Returns markdown-formatted task list with legend and sorted by creation time. Should be called frequently to stay organized.
  • update_tasks(tasks: []TaskUpdate): Updates status of one or more tasks and returns full list. Helps maintain planning workflow by tracking progress.

Configuration System

Uses a three-tier config system (defaults → file → environment variables):

  • Server mode: stdio (default) or http
  • Planning limits: max tasks (100), max goal length (1000), max task length (500)
  • Environment variables prefixed with PLANNING_ (e.g., PLANNING_SERVER_MODE)

Development Guidelines

Code Patterns

Error Handling: All functions return descriptive errors. MCP handlers convert errors to CallToolResult with IsError: true.

Validation: Input validation happens at multiple layers - MCP parameter parsing, planning manager limits, and config validation.

Logging: Uses structured logging (slog) throughout. All operations log at appropriate levels with contextual fields.

Testing Approach

The project structure suggests unit testing at the package level. When adding tests:

  • Test planning manager methods for concurrent access
  • Mock MCP requests for server handler testing
  • Test configuration loading and validation edge cases
  • Verify task ID generation is deterministic

Key Dependencies

  • github.com/mark3labs/mcp-go: MCP protocol implementation
  • github.com/spf13/viper: Configuration management
  • github.com/spf13/cobra: CLI framework
  • github.com/charmbracelet/fang: Enhanced CLI experience

Important Constraints

Stateless Design: No persistent storage - all data is in-memory. This is intentional for the planning use case.

Deterministic IDs: Task IDs must remain consistent. Never change the ID generation algorithm without migration strategy.

MCP Compliance: All tool responses must follow MCP schema. Responses include both success messages and full task lists where appropriate.

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.