From d240d2382bd245e21ea44d0d669e3e68fb268b66 Mon Sep 17 00:00:00 2001
From: Amolith <amolith@secluded.site>
Date: Fri, 8 Aug 2025 15:23:32 -0600
Subject: [PATCH] docs: enhance AGENTS.md with detailed architectural nuances
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add comprehensive documentation of non-obvious implementation details:
- Clarify task ID generation (8 hex chars from SHA256)
- Document silent duplicate task detection behavior
- Explain atomic update pattern in UpdateTasks method
- Detail task list ordering (sorted by creation time)
- Add helper function patterns for MCP responses
- Include config file search paths and naming
- Add test running and maintenance commands

🩷 Generated with Crush
Co-Authored-By: 🩷 Crush <crush@charm.land>
---
 AGENTS.md | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 67167fb7857028e450f0f5c4b634b45e637c2215..f32a8bfb9fe5684e19469b03e1b2e9b65759ae97 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,6 +22,13 @@ just reuse        # Check license/copyright headers
 just build        # Build binary
 just run          # Run server directly
 just install      # Install to GOPATH/bin
+
+# Running specific tests
+go test -v -run TestName ./internal/mcp  # Run single test by name
+go test -v ./internal/planning           # Run tests for specific package
+
+# Maintenance
+go mod tidy       # Clean up unused dependencies
 ```
 
 The project requires license headers (SPDX format) on all source files and uses REUSE for compliance checking.
@@ -40,9 +47,11 @@ The project requires license headers (SPDX format) on all source files and uses
 
 ### 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.
+**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.
 
-**Thread Safety**: The planning manager uses `sync.RWMutex` for concurrent access. All public methods properly lock/unlock.
+**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.
+
+**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.
 
 **Status System**: Tasks use emoji indicators with specific meanings:
 
@@ -72,12 +81,16 @@ 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`)
+- Config file search paths (in order): current directory, `$HOME/.config/planning-mcp-server`, `/etc/planning-mcp-server`
+- Config file name: `planning-mcp-server.toml`
 
 ## Development Guidelines
 
 ### Code Patterns
 
-**Error Handling**: All functions return descriptive errors. MCP handlers convert errors to `CallToolResult` with `IsError: true`.
+**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.
+
+**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.
 
 **Validation**: Input validation happens at multiple layers - MCP parameter parsing, planning manager limits, and config validation.