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.

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

Use this tool to add progress updates, notes, or activity records to an issue'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 issue 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:

• Issue ID: The unique identifier of the trellis issue 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 issue.

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.

Creates a new issue in the task trellis system

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

Available issue 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 issues

• '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:

• Issues support hierarchical organization via parent relationships

• Prerequisites define execution order dependencies between issues

• 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

Deletes an issue from the task trellis system

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

Safety considerations:

• Standard deletion validates relationships and prevents deletion of issues with dependencies

• Issues with children or that serve as prerequisites for other issues 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 issue and all associated metadata permanently

• Updates parent-child relationships by removing deleted issue from parent's children list

• Other issues referencing this as a prerequisite may become invalid

• Historical references in logs and activity trails are preserved but point to non-existent issue

Best practices:

• Verify issue 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 issue ID before proceeding.

Gets an issue from the task trellis system

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

Key information retrieved:

• Issue 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 issue 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.

Gets the next available issue of a specific type

Use this tool to find the next available issue that's ready to work on. Essential for discovering what work is available when you're ready to start on a new project, epic, feature, or task.

Behavior:

• Returns the highest priority available issue of the specified type

• Does not modify task status or claim ownership

• Finds issues that are ready to work on (all prerequisites complete)

• Helps you discover what work is available without having to browse through all issues

Available issue types:

• 'project': Top-level containers

• 'epic': Large features within projects

• 'feature': Specific functionality within epics

• 'task': Individual work items

Required parameters:

• 'issueType': Must specify exactly one object type (project, epic, feature, or task)

Optional parameters:

• 'scope': Limits search to issues within a specific project or area (e.g., 'P-project-name')

Usage patterns:

• Find next project to work on: issueType='project'

• Find which epic to tackle next in a project: issueType='epic', scope='P-project-name'

• Discover what feature needs work: issueType='feature'

• Get the next task ready for development: issueType='task'

• Find work within a specific project scope: issueType='task', scope='P-specific-project'

Return format:

• Success: Returns complete issue object with all metadata, prerequisites, and readiness status

• No issues available: Returns appropriate message indicating no available issues of the specified type

• Error cases: Returns error details with specific failure reasons

Essential for discovering what work is ready to be done. Use this when you need to know what project, epic, feature, or task you should work on next without having to manually browse through all the available issues.

Lists issues from the task trellis system

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

Available issue 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 issues

• 'open': Ready to begin work (default for new issues)

• '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 issue category (project, epic, feature, task) - accepts single value or array

• 'scope': Limit results to a specific project or area of work

• 'status': Find issues in particular states (draft, open, in-progress, done, wont-do) - accepts single value or array

• 'priority': Filter by importance level (high, medium, low) - accepts single value or array

• 'includeClosed': Whether to show completed/archived issues (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

• List features and tasks: type=['feature', 'task']

• List all open objects: status='open' (no type filter)

• Multiple statuses: status=['open', 'in-progress']

• Multiple priorities: priority=['high', 'medium']

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

Updates an existing issue in the task trellis system

Use this tool to modify properties of existing issues 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 issues

• 'open': Ready to begin work (default for new issues)

• '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:

• 'title': Title of the work item

• 'status': Progress state (follows workflow: draft → open → in-progress → done)

• 'priority': Importance level (high, medium, low)

• 'prerequisites': Dependency relationships (add/remove prerequisite issues)

• 'body': Detailed description or content of the work item

• 'force': Bypass certain validation checks when necessary

Common update patterns:

• Update title: title='New task title'

• 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 issue 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.