From 47b42dc4cf687ea540d06d176a7d8dc4ddf8f616 Mon Sep 17 00:00:00 2001
From: Amolith <amolith@secluded.site>
Date: Sat, 2 Aug 2025 10:36:57 -0700
Subject: [PATCH] docs: revise README for end-user focus

- Remove JSON examples and technical implementation details
- Focus on capabilities this provides to AI assistants
- Emphasize user benefits over technical specs
- Reorganize content around "What This Gives Your AI Assistant"
---
 README.md | 65 +++++++++++++++++--------------------------------------
 1 file changed, 20 insertions(+), 45 deletions(-)

diff --git a/README.md b/README.md
index bdb575458d920bfad72107e1fb9b0efbce721b8c..4d0f39cc9467fd66196aae1fe8f2173e1b79156b 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,19 @@
 
 A Model Context Protocol (MCP) server that provides planning tools for LLMs to thoroughly plan their actions before getting started and pivot during execution when needed.
 
-## Features
+## What This Gives Your AI Assistant
 
-The server provides four core tools that constitute a comprehensive planning workflow:
+This MCP server enables your AI assistant to:
+
+- **Set clear goals** for complex tasks and keep them visible throughout the work
+- **Break down work** into manageable, trackable tasks with progress indicators  
+- **Stay organized** with persistent task lists that survive across conversations
+- **Track progress** with visual status indicators (☐ pending, ⟳ in progress, ☑ completed, ☒ failed)
+- **Adapt plans** by adding tasks, updating status, and pivoting when needed
+
+## Core Capabilities
+
+The server provides four essential planning tools:
 
 - **`update_goal`**: Set or update the overarching goal for your planning session
 - **`add_tasks`**: Add one or more tasks to work on. Break tasks down into the smallest units of work possible and track progress.
@@ -76,22 +86,13 @@ For web-based integrations:
 - `--generate-config`: Generate example configuration
 - `--version, -v`: Show version
 
-## Tool Examples
-
-### Setting a Goal
+## How Your AI Assistant Uses This
 
-```json
-{
-  "name": "update_goal",
-  "arguments": {
-    "goal": "Create a comprehensive MCP server for task planning and management"
-  }
-}
-```
+### Setting Goals
 
-Response: `Goal "Create a comprehensive MCP server for task planning and management" saved! You probably want to add one or more tasks now.`
+Your AI assistant can establish clear objectives that stay visible throughout the planning session, helping maintain focus on the overall purpose.
 
-### Adding Tasks
+### Planning Tasks
 
 When you first add tasks to an empty planning session, the tool provides guidance and shows your complete plan:
 
@@ -105,16 +106,10 @@ When adding tasks to an existing planning session, the tool keeps things brief:
 - Shows your updated task list (same format as `get_tasks`)
 - No repetitive instructions - just your updated plan
 
-### Getting Task Status
+### Tracking Progress
 
-```json
-{
-  "name": "get_tasks",
-  "arguments": {}
-}
-```
+Your AI assistant gets a clear view of all tasks with visual status indicators:
 
-Response:
 ```
 **Goal:** Create a comprehensive MCP server for task planning and management
 
@@ -126,29 +121,9 @@ Legend: ☐ pending  ⟳ in progress  ☑ completed
 ☐ Build MCP server integration [i9j0k1l2]
 ```
 
-### Updating Task Status
-
-```json
-{
-  "name": "update_task_status",
-  "arguments": {
-    "task_id": "a1b2c3d4",
-    "status": "completed"
-  }
-}
-```
-
-Response:
-```
-**Goal:** Create a comprehensive MCP server for task planning and management
+### Updating Status
 
-Legend: ☐ pending  ⟳ in progress  ☑ completed
-☑ Set up project structure [a1b2c3d4]
-  Create Go module, directories, and basic files
-⟳ Implement core planning logic [e5f6g7h8]
-  Create Goal and Task data structures with deterministic IDs
-☐ Build MCP server integration [i9j0k1l2]
-```
+As work progresses, your AI assistant can update task statuses and immediately see the updated plan with all changes reflected.
 
 ## Task Status Indicators