@langadventurellc/task-trellis-mcp 1.0.1 → 1.2.0

package/README.md

@@ -1,19 +1,17 @@
 # Task Trellis MCP
 
-> Transform AI coding chaos into organized productivity
+**Project planning and task management built specifically for AI agents**
 
 [![npm version](https://badge.fury.io/js/%40langadventurellc%2Ftask-trellis-mcp.svg)](https://www.npmjs.com/package/@langadventurellc/task-trellis-mcp)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 
-An MCP (Model Context Protocol) server that greatly improves how AI coding agents handle complex projects. Task Trellis helps track requirements for projects, breaks them down into smaller manageable parts until you have trackable and assignable tasks with built-in workflow management, dependency handling, and progress tracking.
+Task Trellis is an MCP server for project planning and task management built specifically for AI agents. It helps by breaking down complex projects and tracking their progress with built-in task management, complete with progress tracking, dependency management, and workflow automation. By default, all data is stored locally in Markdown files.
 
-Primarily built as an alternative to managing the creation and use of agent-created requirements, specifications and checklists. This tool will help make that more organized and less chaotic.
-
-Basically, it's like Jira for coding agents.
+Primarily built as a much better alternative to managing markdown checklists. Task Trellis will make it easier to define requirements, specifications, and tasks in a structured way that the agents can actually use directly.
 
 ## Table of Contents
 
-- [At a glance?](#at-a-glance)
+- [At a Glance](#at-a-glance)
 - [Why Task Trellis?](#why-task-trellis)
 - [Core Benefits](#core-benefits)
 - [Usage](#usage)
@@ -21,61 +19,24 @@ Basically, it's like Jira for coding agents.
 - [Project Hierarchy](#project-hierarchy)
 - [Prerequisites & Dependencies](#prerequisites--dependencies)
 - [File Storage](#file-storage)
-- [Installation](#installation)
-- [Quick Test](#quick-test)
-- [Configuration Options](#configuration-options)
+- [Installation and Configuration](#installation-and-configuration)
 - [Troubleshooting](#troubleshooting)
 
 ## At a Glance
 
-```
-// Simple tasks
-Task: Auth endpoint
-Task: Token refresh
-
-// Moderate sized feature
-Feature: API
- ├── Task: Auth endpoint
- └── Task: Token refresh
-
-// Large project
-Project
- ├── Epic: Login
- │    ├── Feature: UI
- │    │     ├── Task: Email form validation
- │    │     └── Task: Error handling
- │    └── Feature: API
- │          ├── Task: Auth endpoint
- │          └── Task: Token refresh
-```
-
-**Small tasks (one or several tasks that don't necessarily need the benefit of a unifying context)**
-
-> **user:** /create-tasks-trellis create some standalone tasks to remove the console.log usage from the app  
-> _(agent creates and adds the individual tasks that the agent will work on later)_
+Task Trellis works with issues that are projects, epics, features or tasks.
 
-**Moderate sized tasks (most use cases - a feature that gets broken down into a number of workable tasks)**
+**Tasks** are the most important type of issue. This is where the actual work gets done. Each task is a specific piece of work that needs to be completed in order to achieve the project's goals. The other issue types are too big to be a task and they exist to help organize and manage multiple tasks to accomplish a particular goal. Tasks can be standalone or part of a larger feature.
 
-> **user:** /create-features-trellis add posthog analytics to existing web pages  
-> _(agent creates and adds feature requirements document to Task Trellis)_  
-> **user:** /create-tasks-trellis (feature-id)  
-> _(agent creates and adds the individual tasks that the agent will work on later)_
+**Features** are the next level up from tasks. They represent the requirements and functionality needed to deliver a specific aspect of the project. Features can be standalone or a part of a larger epic.
 
-**Large projects (when there's a lot involved that benefits from several layers of refinement)**
+**Epics** are next after features. They represent a significant deliverable or a large body of work that can be broken down into multiple features and tasks. Epics can be standalone or a part of a larger project.
 
-> **user:** /create-project-trellis add user authentication with registration and login pages, using supabase for authentication  
-> _(agent creates and adds project requirements document to Task Trellis)_  
-> **user:** /create-epics-trellis (project-id)  
-> _(agent creates and adds epics that break down the project into distinct, yet still large bodies of work)_  
-> **user:** /create-features-trellis (epic-id)  
-> _(agent creates and adds features that further add detail and context to smaller bodies of work)_  
-> **user:** /create-tasks-trellis (feature-id)  
-> _(agent creates and adds the individual tasks that the agent will work on later)_
+**Projects** are the highest level of organization. They represent the overall initiative or goal that encompasses multiple epics, features, and tasks. Projects provide a way to group related work and track progress at a high level.
 
-**Now do the thing**
+Depending on the size of the effort, you can choose to create a project with epics, features, and tasks, or you can create standalone tasks as needed. Once you have your tasks defined, you can easily manage and track their progress through the Task Trellis MCP tools.
 
-> **user:** /implement-task-trellis  
-> _(agent grabs the next available task and does it)_
+Currently, all Task Trellis issues are stored as markdown files in the `.trellis` folder in the root of your project. This makes it unsuitable for projects with multiple developers, but a remote option is in development now and should be available soon.
 
 ## Why Task Trellis?
 
@@ -118,21 +79,22 @@ Project
 See sample prompts (written as Claude Code slash commands): [Sample Prompts](docs/sample_prompts/index.md)
 
 1. **Create Tasks**
-   - For large projects
-     - Create a project
-     - Create epics to group features
-     - Create features to break down epics
-     - Create tasks for specific work items
-   - For medium-sized projects
-     - Create standalone feature
-     - Create tasks directly under the feature
-   - For small tasks
-     - Create standalone tasks
+   - Determine your starting point based on the expected size of your project
+     - **Project** - For sprawling initiatives with many moving parts
+     - **Epic** - For large feature groupings
+     - **Feature** - For specific functionality
+     - **Task** - For individual work items
 
 2. **Claim & Work on Tasks**
    - AI agent claims next available task
+     - Excludes tasks that have incomplete prerequisites
+     - Grabs the next highest priority available task
+     - Mark a task as `draft` if you don't want it to be worked on yet - it won't be claimed when the tool looks for the next available task
    - Works on the specific task requirements
    - Marks task complete with file changes documented
+     - Automatically tracks which files were modified
+     - Logs summary of changes made
+     - Work done in the future could reference this to better understand the current state of the project
 
 3. **Track Progress**
    - View completed vs. pending work
@@ -141,25 +103,26 @@ See sample prompts (written as Claude Code slash commands): [Sample Prompts](doc
 
 ## Available Tools
 
-### Core Object Management
+### Core Issue Management
 
-- **create_object** - Create projects, epics, features, or tasks with hierarchical relationships
-- **update_object** - Modify object properties, status, priority, or prerequisites
-- **get_object** - Retrieve detailed object information with history and relationships
-- **list_objects** - Query and filter objects by type, status, priority, or scope
-- **delete_object** - Remove objects (with dependency validation)
-- **replace_object_body_regex** - Make targeted content edits using regex patterns
+- **create_issue** - Create projects, epics, features, or tasks with hierarchical relationships
+- **update_issue** - Modify issue properties, status, priority, or prerequisites
+- **get_issue** - Retrieve detailed issue information with history and relationships
+- **list_issues** - Query and filter issues by type, status, priority, or scope (returns issue summaries)
+- **delete_issue** - Remove issues (with dependency validation)
+- **replace_issue_body_regex** - Make targeted body content edits using regex patterns
 
 ### Task Workflow Management
 
 - **claim_task** - Claim available tasks for execution with automatic priority ordering
 - **complete_task** - Mark tasks complete with file change documentation
-- **append_object_log** - Add progress notes and status updates to task history
+- **append_issue_log** - Add progress notes and status updates to task history (occurs automatically on task completion)
+- **append_modified_files** - Record files modified during task execution with change descriptions (occurs automatically on task completion)
 
 ### System Management
 
 - **activate** - Initialize the task system (if not configured via command line)
-- **prune_closed** - Clean up old completed/cancelled objects for maintenance
+- **prune_closed** - Clean up old completed/cancelled issues for maintenance
 
 ## Project Hierarchy
 
@@ -172,12 +135,6 @@ Project (Top-level container)
         └── Task (Individual work items)
 ```
 
-**Supported Patterns:**
-
-- Full hierarchy: `Project → Epic → Feature → Task`
-- Simplified: `Feature → Task`
-- Standalone: `Task` only
-
 ## Prerequisites & Dependencies
 
 Tasks can have prerequisites that must be completed before they become available:
@@ -212,6 +169,22 @@ your-project/
                                     └── T-completed-task-id.md
 ```
 
+### Epic-Only Hierarchy
+
+```
+your-project/
+└── .trellis/
+    └── e/
+        └── E-epic-id/
+            └── f/
+                └── F-feature-id/
+                    └── t/
+                        ├── open/
+                        │   └── T-task-id.md
+                        └── closed/
+                            └── T-completed-task-id.md
+```
+
 ### Feature-Only Hierarchy
 
 ```
@@ -238,195 +211,11 @@ your-project/
             └── T-completed-task-id.md
 ```
 
-Each object is stored as a Markdown file with YAML frontmatter metadata and content body.
-
-## Installation
-
-### Claude Code
-
-The easiest way to install Task Trellis MCP in Claude Code:
-
-```bash
-claude mcp add @langadventurellc/task-trellis-mcp --projectRootFolder "$(pwd)"
-```
-
-Or (you'll be required to call the activate tool once to set the project root folder):
-
-```bash
-claude mcp add @langadventurellc/task-trellis-mcp
-```
-
-### VS Code with GitHub Copilot
-
-1. Add Task Trellis to your VS Code settings. Open your settings JSON file and add:
-
-```json
-{
-  "github.copilot.chat.mcpServers": {
-    "task-trellis": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@langadventurellc/task-trellis-mcp",
-        "--projectRootFolder",
-        "${workspaceFolder}"
-      ]
-    }
-  }
-}
-```
-
-### Cursor
-
-Install Task Trellis MCP in Cursor by adding to your Cursor settings:
-
-**Method 1: Via Settings UI**
-
-1. Open Cursor Settings (⌘/Ctrl + ,)
-2. Search for "MCP"
-3. Add new server with:
-   - **Name**: `task-trellis`
-   - **Command**: `npx`
-   - **Args**: `["-y", "@langadventurellc/task-trellis-mcp", "--projectRootFolder", "${workspaceFolder}"]`
-
-**Method 2: Via Configuration File**
-Add to your Cursor configuration:
-
-```json
-{
-  "mcpServers": {
-    "task-trellis": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@langadventurellc/task-trellis-mcp",
-        "--projectRootFolder",
-        "${workspaceFolder}"
-      ]
-    }
-  }
-}
-```
+Each issue is stored as a Markdown file with YAML frontmatter metadata and content body.
 
-### Windsurf
+## Installation and Configuration
 
-Add Task Trellis to your Windsurf MCP configuration:
-
-```json
-{
-  "mcpServers": {
-    "task-trellis": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@langadventurellc/task-trellis-mcp",
-        "--projectRootFolder",
-        "${workspaceRoot}"
-      ]
-    }
-  }
-}
-```
-
-### Cline (VS Code Extension)
-
-1. Add Task Trellis to your Cline MCP servers in VS Code settings:
-
-```json
-{
-  "cline.mcpServers": {
-    "task-trellis": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@langadventurellc/task-trellis-mcp",
-        "--projectRootFolder",
-        "${workspaceFolder}"
-      ]
-    }
-  }
-}
-```
-
-### Continue (VS Code Extension)
-
-1. Add to your Continue configuration file (`~/.continue/config.json`):
-
-```json
-{
-  "mcpServers": {
-    "task-trellis": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@langadventurellc/task-trellis-mcp",
-        "--projectRootFolder",
-        "/path/to/your/project"
-      ]
-    }
-  }
-}
-```
-
-### Other MCP Clients
-
-For any MCP-compatible client, use this configuration:
-
-```json
-{
-  "mcpServers": {
-    "task-trellis": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@langadventurellc/task-trellis-mcp",
-        "--projectRootFolder",
-        "/absolute/path/to/project"
-      ]
-    }
-  }
-}
-```
-
-## Quick Test
-
-After installation, test that Task Trellis is working by asking your AI assistant:
-
-> "Create a new project called 'My Test Project'"
-
-If configured correctly, the AI should respond with a confirmation and create the project structure in your specified project root folder.
-
-## Configuration Options
-
-The Task Trellis MCP server supports these command-line options:
-
-- `--mode <mode>` - Server mode (default: "local")
-  - `local` - Use local file-based storage
-  - `remote` - Use remote repository (planned feature)
-
-- `--projectRootFolder <path>` - Project root folder path
-  - Creates a `.trellis` folder inside the project root for task storage
-  - Example: `--projectRootFolder /path/to/my-project` creates `/path/to/my-project/.trellis/`
-
-**Advanced Configuration Example:**
-
-```json
-{
-  "mcpServers": {
-    "task-trellis": {
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "@langadventurellc/task-trellis-mcp",
-        "--mode",
-        "local",
-        "--projectRootFolder",
-        "/path/to/your/project"
-      ]
-    }
-  }
-}
-```
+See [installation instructions](docs/installation.md).
 
 ## Troubleshooting
 

package/dist/__tests__/e2e/autoPrune.e2e.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=autoPrune.e2e.test.d.ts.map

package/dist/__tests__/e2e/autoPrune.e2e.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoPrune.e2e.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/autoPrune.e2e.test.ts"],"names":[],"mappings":""}