Task Trellis MCP

Creates a new object in the task trellis system

Use this tool to create new objects such as tasks, projects, or other work items within the task management hierarchy. Objects can have parent-child relationships and dependencies through prerequisites.

Available object types and hierarchy requirements:

• 'project': Top-level containers, cannot have a parent
• 'epic': Can have no parent or a project as a parent
• 'feature': Can have no parent or an epic as a parent
• 'task': Can have no parent or a feature as a parent

Supported hierarchy structures:

• Full hierarchy: project → epic → feature → task
• Simplified: epic → feature → task
• Simplified: feature → task
• Standalone: epic
• Standalone: task

Available status values:

• 'draft': Initial state for new objects
• 'open': Ready to begin work (default)
• 'open': Ready to begin work
• 'in-progress': Currently being worked on
• 'done': Completed successfully
• 'wont-do': Cancelled or decided against

Available priority values:

• 'high': Critical or urgent work
• 'medium': Standard priority (default)
• 'low': Nice-to-have or future work

Key aspects:

• Objects support hierarchical organization via parent relationships
• Prerequisites define execution order dependencies between objects
• Parent-child relationships must follow the hierarchy rules above
• The system validates parent types during creation

Best practices:

• Use descriptive titles that clearly indicate the work to be done
• Follow the hierarchy constraints for proper organization
• Set appropriate status based on current work state
• Define prerequisites to ensure proper task ordering
• Include detailed descriptions to provide context for the work

Updates an existing object in the task trellis system

Use this tool to modify properties of existing objects such as changing status, priority, prerequisites, or content. Essential for managing work item lifecycle and maintaining project state.

Available status values:

• 'draft': Initial state for new objects
• 'open': Ready to begin work (default for new objects)
• 'in-progress': Currently being worked on
• 'done': Completed successfully
• 'wont-do': Cancelled or decided against

Available priority values:

• 'high': Critical or urgent work
• 'medium': Standard priority
• 'low': Nice-to-have or future work

Updatable properties:

• 'status': Progress state (follows workflow: draft → open → in-progress → done)
• 'priority': Importance level (high, medium, low)
• 'prerequisites': Dependency relationships (add/remove prerequisite objects)
• 'body': Detailed description or content of the work item
• 'force': Bypass certain validation checks when necessary

Common update patterns:

• Mark task as ready: status='open'
• Start working: status='in-progress'
• Change priority: priority='high'
• Add dependencies: prerequisites=[...existing, 'new-prereq-id']
• Update description: body='detailed work description'
• Complete work: status='done'
• Cancel work: status='wont-do'

The update maintains object integrity by validating relationships and preserving audit trail. Use 'force=true' only when bypassing standard validation is necessary for administrative operations.

Updates automatically refresh the 'updated' timestamp while preserving creation metadata and change history.

Replaces portions of an object's body using regular expressions

Use this tool to make targeted edits to specific sections of an object's body content without recreating the entire text. This is safer and more efficient than wholesale body replacement for surgical text modifications.

The tool uses regex pattern matching with multiline and global capabilities, similar to Python's re.sub(). When allowMultipleOccurrences is false (default), it prevents unintended bulk replacements by throwing an error if multiple matches are found.

Regex Features:

• Multiline matching: patterns can span multiple lines
• Dot-all mode: . matches newlines
• Backreferences: use \1, \2, etc. in replacement text
• Case-sensitive matching (use (?i) flag in pattern for case-insensitive)

Common use cases:

• Update specific sections of documentation
• Modify code snippets within object descriptions
• Replace outdated information while preserving structure
• Update specific parameters or values
• Fix formatting or content errors in targeted areas

Safety features:

• Single-match enforcement (unless explicitly allowed)
• Pattern validation before execution
• Graceful error handling with detailed messages
• Original content preservation on pattern mismatch

Example patterns:

• Simple text: "old text" → "new text"
• With context: "(section:\s*)old content(\s*end)" → "\1new content\2"
• Multi-line: "BEGIN.*?END" → "BEGIN\nnew content\nEND"
• Backreferences: "(\w+) (\w+)" → "\2, \1"

The replacement preserves all object metadata and relationships while only modifying the body content that matches your pattern.

Gets an object from the task trellis system

Use this tool to retrieve detailed information about a specific object by its unique ID. Returns the complete object data including metadata, relationships, content, and activity history.

Key information retrieved:

• Object metadata (type, title, status, priority, timestamps)
• Hierarchical relationships (parent, children, prerequisites)
• Content body and description
• Activity log and change history
• File associations and modifications
• Current state and progress indicators

Usage scenarios:

• Review task details before starting work
• Check object status and dependencies
• Examine change history and activity logs
• Understand parent-child relationships
• Verify prerequisite completion
• Access associated file changes

Essential for understanding the full context of a work item before making modifications or planning next steps.

Deletes an object from the task trellis system

Use this tool to permanently remove objects from the task hierarchy. Exercise caution as deletion affects related objects and cannot be easily undone.

Safety considerations:

• Standard deletion validates relationships and prevents deletion of objects with dependencies
• Objects with children or that serve as prerequisites for other objects may be protected
• Use 'force=true' to bypass safety checks for administrative cleanup
• Consider updating status to 'cancelled' instead of deletion for audit trail preservation

Deletion impacts:

• Removes object and all associated metadata permanently
• Updates parent-child relationships by removing deleted object from parent's children list
• Other objects referencing this as a prerequisite may become invalid
• Historical references in logs and activity trails are preserved but point to non-existent object

Best practices:

• Verify object has no active dependencies before deletion
• Use list/get tools to understand relationships before deletion
• Prefer status updates to 'cancelled' over deletion for important work items
• Use force deletion only for cleanup of test data or administrative maintenance

This operation is irreversible - ensure you have the correct object ID before proceeding.

Lists objects from the task trellis system

Use this tool to retrieve and filter objects based on various criteria. Essential for discovering existing work items, understanding project structure, and finding objects that need attention.

Available object types:

• 'project': Top-level containers
• 'epic': Large features within projects
• 'feature': Specific functionality within epics
• 'task': Individual work items

Available status values:

• 'draft': Initial state for new objects
• 'open': Ready to begin work (default for new objects)
• 'in-progress': Currently being worked on
• 'done': Completed successfully
• 'wont-do': Cancelled or decided against

Available priority values:

• 'high': Critical or urgent work
• 'medium': Standard priority
• 'low': Nice-to-have or future work

Key filtering options:

• 'type': Filter by object category (project, epic, feature, task)
• 'scope': Limit results to a specific project or area of work
• 'status': Find objects in particular states (draft, open, in-progress, done, wont-do)
• 'priority': Filter by importance level (high, medium, low)
• 'includeClosed': Whether to show completed/archived objects (defaults to false)

Usage patterns:

• List all tasks in progress: type='task', status='in-progress'
• Find high priority work: priority='high', includeClosed=false
• Review project scope: type='project', scope='specific-project'
• Audit completed work: includeClosed=true, status='done'
• Find cancelled items: status='wont-do', includeClosed=true

The results provide object summaries (TrellisObjectSummary instances) containing id, type, title, status, priority, parent, prerequisites, childrenIds, created, and updated fields to enable efficient filtering and further operations.

Appends content to an object's log in the task trellis system

Use this tool to add progress updates, notes, or activity records to an object's audit trail. Essential for tracking work history, documenting decisions, and maintaining transparency in task execution.

Log entry purposes:

• Record progress milestones and status changes
• Document challenges encountered and solutions applied
• Note important decisions or changes in approach
• Track time spent or resources used
• Log external dependencies or blockers
• Record completion details and outcomes

Log content guidelines:

• Use clear, descriptive entries with context
• Include timestamps (automatically added by system)
• Reference specific files, commits, or external resources when relevant
• Note any changes to scope, requirements, or approach
• Document lessons learned or insights gained

Activity tracking patterns:

• Starting work: "Started implementation of feature X"
• Progress updates: "Completed database schema changes, moving to API layer"
• Blocking issues: "Blocked on external API access, contacted team"
• Problem resolution: "Resolved memory leak by optimizing data structure"
• Completion: "Task completed, all tests passing, PR submitted"

The log creates a permanent audit trail that helps with project retrospectives, debugging issues, and understanding work evolution over time.

Appends modified files information to a trellis object in the task trellis system

Use this tool to record files that have been modified during task execution, along with descriptions of the modifications made. This helps maintain a comprehensive record of changes associated with each work item for tracking and audit purposes.

File modification tracking purposes:

• Record which files were changed during task execution
• Document the nature of changes made to each file
• Maintain audit trail of file-level modifications
• Support code review and change management processes
• Enable impact analysis for future changes

Input requirements:

• Object ID: The unique identifier of the trellis object to update
• Files Changed: A record mapping file paths to descriptions of modifications

File path guidelines:

• Use relative paths from project root (e.g., "src/components/Button.tsx")
• Include file extensions for clarity
• Use forward slashes for path separators

Description guidelines:

• Provide clear, concise descriptions of what was changed
• Focus on the purpose and impact of changes rather than implementation details
• Use consistent terminology across related modifications

The tool automatically merges descriptions for files that were previously modified, creating a comprehensive change history for each file within the context of the trellis object.

Claims a task in the task trellis system

Use this tool to assign yourself to available tasks for execution. Essential for AI agents to pick up work items from the task queue and begin execution.

Claiming behavior:

• Without 'taskId': Claims the next available task based on priority and readiness
• With 'taskId': Claims a specific task by ID if available and ready
• 'scope': Limits claiming to tasks within a specific project or area
• 'force': Overrides normal claiming restrictions (use with caution)

Task readiness criteria:

• Task status allows claiming (typically 'draft' or 'open' states)
• All prerequisites are satisfied (prerequisite tasks completed)
• Task is not already claimed by another agent
• Task falls within specified scope if provided

Claiming workflow:

1. System evaluates available tasks against readiness criteria
2. Selects highest priority task that meets requirements
3. Updates task status to 'in-progress
4. Associates task with the claiming agent
5. Returns claimed task details for execution

Common patterns:

• Claim any ready task: (no parameters)
• Claim from project: scope='P-project-name'
• Claim specific task: taskId='T-specific-task-id'
• Force claim blocked task: taskId='T-task-id', force=true

Essential for autonomous task execution workflows where agents need to discover and claim work items dynamically.

Completes a task in the task trellis system

Use this tool to mark a task as finished and record completion details. Critical for task lifecycle management and maintaining accurate project status.

Required completion data:

• 'taskId': Unique identifier of the task being completed
• 'summary': Concise description of what was accomplished
• 'filesChanged': Map of modified files with descriptions of changes made

Completion process:

1. Validates task is in a completable state ('in-progress')
2. Updates task status to 'done'
3. Records completion timestamp and summary
4. Associates file changes with the task for traceability
5. Updates parent-child relationships and dependency chains
6. Triggers any dependent tasks that were waiting for this completion

File change tracking:

• Key: relative file path from project root
• Value: description of changes made to that file
• Example: {'src/api/users.ts': 'Added user authentication endpoints', 'tests/auth.test.ts': 'Added comprehensive auth test coverage'}

Best practices:

• Provide clear, actionable summaries that explain the outcome
• Document all meaningful file changes for future reference
• Complete tasks only when all acceptance criteria are met
• Verify dependent tasks can now proceed before completion
• Include any important notes or lessons learned in the summary

Task completion automatically notifies dependent tasks and may trigger workflow progression for related work items.

Prunes closed objects from the task trellis system

Use this tool for maintenance and cleanup of completed, cancelled, or otherwise closed objects that are no longer needed. Essential for system hygiene and performance optimization.

Pruning criteria:

• 'age': Minimum age in minutes since object closure (required)
• 'scope': Limit pruning to specific project or area (optional)
• Objects must be in closed states (completed, cancelled, archived)
• Objects must not have active dependencies or relationships

Safety mechanisms:

• Only removes truly closed objects (completed, cancelled, etc.)
• Validates no active objects depend on pruned items
• Preserves objects referenced by active work
• Maintains referential integrity of remaining system

Common usage patterns:

• Daily cleanup: age=1440 (24 hours)
• Weekly maintenance: age=10080 (7 days)
• Project closure: scope='project-name', age=4320 (3 days)
• System cleanup: age=43200 (30 days)

Pruning benefits:

• Reduces database size and improves query performance
• Removes clutter from active task views
• Prevents accumulation of obsolete work items
• Maintains focus on current and relevant tasks

Use regularly as part of system maintenance to keep the task trellis clean and performant. Consider project lifecycles and audit requirements when setting age thresholds.

This operation is permanent - pruned objects cannot be recovered.

Activates the task trellis system in local or remote mode

Use this tool to initialize and configure the task trellis system for operation. Must be called before any other task management operations can be performed.

Activation modes:

• 'local': Uses local file system for task storage and management
• 'remote': Connects to remote task trellis service via API

Local mode requirements:

• 'projectRoot': Absolute path to project directory where tasks will be stored
• Creates local .task-trellis directory for data persistence
• Suitable for single-user development workflows
• No network dependencies once activated

Remote mode requirements:

• 'apiToken': Authentication token for remote service access
• 'remoteProjectId': Unique identifier for remote project instance
• 'url': Service endpoint (optional, uses default if not specified)
• Enables collaborative task management across distributed teams
• Requires network connectivity for all operations

Activation process:

1. Validates mode-specific parameters and connectivity
2. Initializes data storage (local directory or remote connection)
3. Verifies authentication and permissions
4. Sets up task trellis schema and configuration
5. Prepares system for task creation and management

Error conditions:

• Invalid projectRoot path (local mode)
• Authentication failure (remote mode)
• Network connectivity issues (remote mode)
• Insufficient file system permissions (local mode)

Must be successfully completed before using any other task trellis tools. Re-activation with different parameters switches modes and resets system state.