@langadventurellc/task-trellis-mcp 1.2.2 → 1.3.0

package/dist/resources/basic/prompts/create-features.md

@@ -0,0 +1,172 @@
+---
+description: Break down an epic into specific features by analyzing the epic specification
+---
+
+# Create Features Command
+
+Break down an epic into specific features using the Trellis task management system by analyzing the epic specification and gathering additional requirements as needed. Do not attempt to create multiple features in parallel. Do them sequentially one at a time.
+
+## Goal
+
+Analyze an epic's comprehensive specification to create well-structured features that represent implementable functionality, ensuring complete coverage of the epic's scope and enabling effective task decomposition.
+
+**IMPORTANT**: Features must include actual changes, implementations, or deliverables. Do not create features that are purely research tasks or analysis tasks without any tangible output. Since all features and tasks are executed independently without context from other features or tasks, purely analytical work provides no value.
+
+## Process
+
+### 1. Identify Context and Requirements
+
+#### Input
+
+`$ARGUMENTS`
+
+#### Context Determination
+
+The input may contain:
+
+- **Epic ID**: (e.g., "E-user-auth") - Create features within an epic hierarchy
+- **Feature Requirements**: Direct description of standalone functionality needed
+- **Mixed**: Epic ID plus additional feature specifications
+
+#### Instructions
+
+**For Hierarchical Features:**
+
+- Retrieve the epic using MCP `get_issue` to access its comprehensive description, requirements, and parent project context
+
+**For Standalone Features:**
+
+- Analyze the provided requirements directly
+- No parent context needed, focus on the specific functionality described
+
+### 2. Analyze Requirements
+
+**Thoroughly analyze the requirements (epic description OR standalone requirements) to identify natural feature boundaries:**
+
+- **Search codebase** for similar feature patterns or implementations
+- Extract all deliverables and components from the epic description
+- Review architecture diagrams and technical specifications
+- Analyze user stories to identify discrete user-facing functionality
+- Consider non-functional requirements that need specific implementation
+- Group related functionality into cohesive features
+- Identify dependencies between features
+- Note any specific instructions provided in `input`
+
+### 3. Gather Additional Information
+
+**Ask clarifying questions as needed to refine the feature structure:**
+
+Use this structured approach:
+
+- **Ask one question at a time** with specific options
+- **Focus on feature boundaries** - understand what constitutes a complete, testable feature
+- **Identify component relationships** - how features interact with each other
+- **Continue until complete** - don't stop until you have clear feature structure
+
+Key areas to clarify:
+
+- **Feature Boundaries**: What constitutes a complete, testable feature?
+- **Dependencies**: Which features must be implemented before others?
+- **Technical Approach**: How should complex functionality be divided?
+- **Testing Strategy**: How can features be tested independently?
+- **Integration Points**: Where do features interface with each other?
+
+**Example questioning approach:**
+
+```
+How should the user registration feature be scoped?
+Options:
+- A) Basic registration only (email, password, confirmation)
+- B) Full registration with profile setup and email verification
+- C) Registration with social login integration included
+```
+
+Continue until the feature structure:
+
+- Covers all aspects of the epic specification
+- Represents 6-20 tasks worth of work per feature
+- Has clear implementation boundaries
+- Enables independent development and testing
+
+### 4. Generate Feature Structure
+
+For each feature, create:
+
+- **Title**: Clear, specific name (3-5 words)
+- **Description**: Comprehensive explanation including:
+  - Purpose and functionality
+  - Key components to implement
+  - **Detailed Acceptance Criteria**: Specific, measurable requirements that define feature completion, including:
+    - Functional behavior with specific input/output expectations
+    - User interface requirements and interaction patterns
+    - Data validation and error handling criteria
+    - Integration points with other features or systems
+    - Performance benchmarks and response time requirements
+    - Security validation and access control requirements
+    - Browser/platform compatibility requirements
+    - Accessibility and usability standards
+  - Technical requirements
+  - Dependencies on other features
+  - **Implementation Guidance** - Technical approach and patterns to follow
+  - **Testing Requirements** - How to verify the feature works correctly
+  - **Security Considerations** - Input validation, authorization, data protection needs
+  - **Performance Requirements** - Response times, resource usage constraints
+
+**Feature Granularity Guidelines:**
+
+Each feature should be sized appropriately for task breakdown:
+
+- **1-2 hours per task** - When broken down, each task should be completable in 1-2 hours
+- **Independent implementation** - Features should be implementable without blocking other features
+- **Testable boundaries** - Features should have clear success criteria and testing strategies
+
+### 5. Create Features Using MCP
+
+For each feature, call the Task Trellis MCP `create_issue` tool:
+
+- `type`: Set to `"feature"`
+- `parent`: The epic ID (optional - omit for standalone features)
+- `title`: Generated feature title
+- `status`: Set to `"open"` (default, ready to begin work) or `"draft"` unless specified
+- `prerequisites`: List of feature IDs that must complete first
+- `description`: Comprehensive feature description with all elements from step 4
+
+**For standalone features**: Simply omit the `parent` parameter entirely.
+
+### 6. Output Format
+
+After successful creation:
+
+```
+✅ Successfully created [N] features for epic "[Epic Title]"
+
+📋 Created Features:
+1. F-[id1]: [Feature 1 Title]
+   → Dependencies: none
+
+2. F-[id2]: [Feature 2 Title]
+   → Dependencies: F-[id1]
+
+3. F-[id3]: [Feature 3 Title]
+   → Dependencies: F-[id1], F-[id2]
+
+📊 Feature Summary:
+- Total Features: [N]
+```
+
+## Question Guidelines
+
+Ask questions that:
+
+- **Define feature scope**: What's included vs excluded?
+- **Clarify technical approach**: Specific technologies or patterns?
+- **Identify dependencies**: Build order and integration points?
+- **Consider testing**: How to verify feature completeness?
+
+<rules>
+  <critical>Use MCP tools for all operations (create_issue, get_issue, etc.)</critical>
+  <critical>Ask one question at a time with specific options</critical>
+  <critical>Continue asking questions until you have complete understanding of feature boundaries</critical>
+  <important>Feature descriptions must be detailed enough for task creation</important>
+  <important>Include implementation guidance and testing requirements</important>
+</rules>

package/dist/resources/basic/prompts/create-project.md

@@ -0,0 +1,128 @@
+---
+description: Create a new project in the Trellis task management system by analyzing specifications and gathering requirements
+---
+
+# Create Project Trellis Command
+
+Create a new project in the Trellis task management system by analyzing specifications provided and gathering additional requirements as needed.
+
+## Goal
+
+Transform project specifications into a comprehensive project definition with full context and requirements that enable other agents to effectively create epics, features, and ultimately implementable tasks.
+
+## Process
+
+### 1. Parse Input Specifications
+
+#### Specification Input
+
+`$ARGUMENTS`
+
+#### Instructions
+
+Read and analyze the specifications:
+
+- Extract key project goals, requirements, and constraints
+
+### 2. Analyze Project Context
+
+**Before gathering requirements, research the existing system:**
+
+- **Search codebase** for similar projects or patterns
+- **Identify existing architecture** and conventions
+- **Document discovered technologies** for consistency
+
+### 3. Gather Additional Requirements
+
+**Continue asking questions until you can create a complete project specification:**
+
+Use this structured approach:
+
+- **Ask one question at a time** with specific options
+- **Focus on decomposition** - break large concepts into smaller components
+- **Clarify boundaries** - understand where one component ends and another begins
+- **Continue until complete** - don't stop until you have full understanding
+
+Key areas to explore:
+
+- **Functional Requirements**: What specific capabilities must the system provide?
+- **Technical Architecture**: What technologies, frameworks, and patterns should be used?
+- **Integration Points**: What external systems or APIs need to be integrated?
+- **User Types**: Who will use this system and what are their needs?
+- **Performance Requirements**: What are the response time, load, and scaling needs?
+- **Security Requirements**: What authentication, authorization, and data protection is needed?
+- **Deployment Environment**: Where and how will this be deployed?
+- **Timeline & Phases**: Are there specific deadlines or phase requirements?
+- **Success Metrics**: How will project success be measured?
+
+**Example questioning approach:**
+
+```
+How should user authentication be handled in this project?
+Options:
+- A) Use existing authentication system (specify integration points)
+- B) Implement new authentication mechanism (specify requirements)
+- C) No authentication needed for this project
+```
+
+Continue asking clarifying questions until you have enough information to create a comprehensive project description that would enable another agent to:
+
+- Understand the full scope and vision
+- Create appropriate epics covering all aspects
+- Make informed technical decisions
+- Understand constraints and requirements
+
+### 4. Generate Project Title and Description
+
+Based on gathered information:
+
+- **Title**: Create a clear, concise project title (5-7 words)
+- **Description**: Write comprehensive project specification including:
+  - Executive summary
+  - Detailed functional requirements
+  - Technical requirements and constraints
+  - Architecture overview
+  - User stories or personas
+  - Non-functional requirements (performance, security, etc.)
+  - Integration requirements
+  - Deployment strategy
+  - **Detailed Acceptance Criteria**: Specific, measurable requirements that define feature completion, including:
+    - Functional behavior with specific input/output expectations
+    - User interface requirements and interaction patterns
+    - Data validation and error handling criteria
+    - Integration points with other features or systems
+    - Performance benchmarks and response time requirements
+    - Security validation and access control requirements
+    - Browser/platform compatibility requirements
+    - Accessibility and usability standards
+  - Any other context needed for epic creation
+
+### 5. Create Project Using MCP
+
+Call the Task Trellis MCP `create_issue` tool to create the project with the following parameters:
+
+- `type`: Set to `"project"`
+- `title`: The generated project title
+- `status`: Set to `"open"` (default, ready to begin work) or `"draft"` unless specified
+- `description`: The comprehensive project description generated in the previous step
+
+### 6. Output Format
+
+After successful creation:
+
+```
+✅ Project created successfully!
+
+📁 Project: [Generated Title]
+📍 ID: [generated-id]
+📊 Status: [actual-status]
+
+📝 Project Summary:
+[First paragraph of description]
+```
+
+<rules>
+  <critical>Use MCP tools for all operations (create_issue, get_issue, activate, etc.)</critical>
+  <critical>Continue asking questions until you have a complete understanding of the requirements</critical>
+  <critical>Ask one question at a time with specific options</critical>
+</rules>

package/dist/resources/basic/prompts/create-tasks.md

@@ -0,0 +1,225 @@
+---
+description: Break down a feature into specific, actionable tasks (1-2 hours each)
+---
+
+# Create Tasks Command
+
+Break down a feature into specific, actionable tasks using the Trellis task management system. Do not attempt to create multiple tasks in parallel. Do them sequentially one at a time.
+
+## Goal
+
+Analyze a feature's comprehensive specification to create granular tasks that can be individually claimed and completed by developers, ensuring complete implementation of the feature with proper testing and security considerations.
+
+## Process
+
+### 1. Identify Context and Requirements
+
+#### Input
+
+`$ARGUMENTS`
+
+#### Context Determination
+
+The input may contain:
+
+- **Feature ID**: (e.g., "F-user-registration") - Create tasks within a feature hierarchy
+- **Task Requirements**: Direct description of standalone work needed
+- **Mixed**: Feature ID plus additional task specifications
+
+#### Instructions
+
+**For Hierarchical Tasks:**
+
+- Retrieve the feature using MCP `get_issue` to access its comprehensive description, requirements, and parent epic/project context
+
+**For Standalone Tasks:**
+
+- Analyze the provided requirements directly
+- No parent context needed, focus on the specific work described
+
+### 2. Analyze Requirements
+
+**Thoroughly analyze the requirements (feature description OR standalone requirements) to identify required tasks:**
+
+- **Search codebase** for similar task patterns or implementations
+- Extract all components and deliverables from the feature description
+- Review implementation guidance and technical approach
+- Identify testing requirements for comprehensive coverage
+- Consider security considerations that need implementation
+- Analyze performance requirements and constraints
+- Group related implementation work
+- Identify task dependencies and sequencing
+- Note any specific instructions provided in `input`
+
+### 3. Gather Additional Information
+
+**Ask clarifying questions as needed to refine the task breakdown:**
+
+Use this structured approach:
+
+- **Ask one question at a time** with specific options
+- **Focus on task boundaries** - understand what constitutes a complete, testable task
+- **Identify implementation details** - specific technical approaches or patterns
+- **Continue until complete** - don't stop until you have clear task structure
+
+Key areas to clarify:
+
+- **Implementation Details**: Specific technical approaches or patterns?
+  - Include unit testing in the tasks for the implementation.
+- **Task Boundaries**: What constitutes a complete, testable task?
+- **Dependencies**: Which tasks must complete before others?
+- **Testing Approach**: Unit tests, integration tests, or both?
+  - Do not create separate tasks just for unit tests. Unit tests should always be included in the same task as the changes to the production code.
+  - Do create separate tasks for integration tests.
+  - If specifically requested, do create separate tasks for performance tests. But, do not add tasks for performance tests unless specifically requested by the user.
+- **Security Implementation**: How to handle validation and authorization?
+
+**Example questioning approach:**
+
+```
+How should the user model validation be implemented?
+Options:
+- A) Basic field validation only (required fields, data types)
+- B) Advanced validation with custom rules and error messages
+- C) Validation with integration to existing validation framework
+```
+
+Continue until the task structure:
+
+- Covers all aspects of the feature specification
+- Represents atomic units of work (1-2 hours each)
+- Has clear implementation boundaries
+- Includes adequate testing and security tasks
+
+### 4. Generate Task Structure
+
+For each task, create:
+
+- **Title**: Clear, actionable description
+- **Description**: Detailed explanation including:
+  - **Detailed Context**: Enough information for a developer new to the project to complete the work, including:
+    - Links to relevant specifications, documentation, or other Trellis issues (tasks, features, epics, projects)
+    - References to existing patterns or similar implementations in the codebase
+    - Specific technologies, frameworks, or libraries to use
+    - File paths and component locations where work should be done
+  - **Specific implementation requirements**: What exactly needs to be built
+  - **Technical approach to follow**: Step-by-step guidance on implementation
+  - **Detailed Acceptance Criteria**: Specific, measurable requirements that define project success, including:
+    - Functional deliverables with clear success metrics
+    - Performance benchmarks (response times, throughput, capacity)
+    - Security requirements and compliance standards
+    - User experience criteria and usability standards
+    - Integration testing requirements with external systems
+    - Deployment and operational readiness criteria
+  - **Dependencies on other tasks**: Prerequisites and sequencing
+  - **Security considerations**: Validation, authorization, and protection requirements
+  - **Testing requirements**: Specific tests to write and coverage expectations
+
+**Task Granularity Guidelines:**
+
+Each task should be sized appropriately for implementation:
+
+- **1-2 hours per task** - Tasks should be completable in one sitting
+- **Atomic units of work** - Each task should produce a meaningful, testable change
+- **Independent implementation** - Tasks should be workable without blocking others
+- **Specific scope** - Implementation approach should be clear from the task description
+- **Testable outcome** - Tasks should have defined acceptance criteria
+
+**Default task hierarchy approach:**
+
+- **Prefer flat structure** - Most tasks should be at the same level
+- **Only create sub-tasks when necessary** - When a task is genuinely too large (>2 hours)
+- **Keep it simple** - Avoid unnecessary complexity in task organization
+
+Group tasks logically:
+
+- **Setup/Configuration**: Initial setup tasks
+- **Core Implementation**: Main functionality (includes unit tests and documentation)
+- **Security**: Validation and protection (includes related tests and docs)
+
+### 5. Create Tasks Using MCP
+
+For each task, call the Task Trellis MCP `create_issue` tool:
+
+- `type`: Set to `"task"`
+- `parent`: The feature ID (optional - omit for standalone tasks)
+- `title`: Generated task title
+- `status`: Set to `"open"` (default, ready to claim) or `"draft"`
+- `priority`: Based on criticality and dependencies (`"high"`, `"medium"`, or `"low"`)
+- `prerequisites`: List of task IDs that must complete first
+- `description`: Comprehensive task description
+
+**For standalone tasks**: Simply omit the `parent` parameter entirely.
+
+### 6. Output Format
+
+After successful creation:
+
+```
+✅ Successfully created [N] tasks for feature "[Feature Title]"
+
+📋 Created Tasks:
+Database & Models:
+  ✓ T-[id1]: Create user database model with validation and unit tests
+  ✓ T-[id2]: Add email verification token system with tests and docs
+
+API Development:
+  ✓ T-[id3]: Create POST /api/register endpoint with tests and validation
+  ✓ T-[id4]: Implement email verification endpoint with tests
+  ✓ T-[id5]: Add rate limiting with monitoring and tests
+
+Frontend:
+  ✓ T-[id6]: Create registration form component with tests and error handling
+  ✓ T-[id7]: Add client-side validation with unit tests
+  ✓ T-[id8]: Implement success/error states with component tests
+
+Integration:
+  ✓ T-[id9]: Write end-to-end integration tests for full registration flow
+
+📊 Task Summary:
+- Total Tasks: [N]
+- High Priority: [X]
+```
+
+## Task Creation Guidelines
+
+Ensure tasks are:
+
+- **Atomic**: Completable in one sitting (1-2 hours)
+- **Specific**: Clear implementation path
+- **Testable**: Defined acceptance criteria. Include instructions for writing unit tests in the same tasks as writing the production code. Integration tests should be in separate tasks.
+- **Independent**: Minimal coupling where possible
+- **Secure**: Include necessary validations
+
+Common task patterns:
+
+- **Model/Schema**: Create with validation, indexing, unit tests, and docs
+- **API Endpoint**: Implement with input validation, error handling, tests, and docs
+- **Frontend Component**: Create with interactivity, state handling, tests, and docs
+- **Security**: Input validation, authorization, rate limiting with tests and docs
+
+## Question Guidelines
+
+Ask questions that:
+
+- **Clarify implementation**: Specific libraries or approaches?
+- **Define boundaries**: What's included in each task?
+- **Identify prerequisites**: What must be built first?
+- **Confirm testing strategy**: What types of tests are needed?
+
+## Priority Assignment
+
+Assign priorities based on:
+
+- **High**: Blocking other work, security-critical, core functionality
+- **Medium**: Standard implementation tasks
+- **Low**: Enhancements, optimizations, nice-to-have features
+
+<rules>
+  <critical>Use MCP tools for all operations (create_issue, get_issue, etc.)</critical>
+  <critical>Each task must be completable in 1-2 hours</critical>
+  <critical>Ask one question at a time with specific options</critical>
+  <critical>Continue asking questions until you have complete understanding of task boundaries</critical>
+  <important>Include testing and documentation within implementation tasks</important>
+  <important>Add security validation with tests where applicable</important>
+</rules>

package/dist/resources/basic/prompts/implement-task.md

@@ -0,0 +1,170 @@
+---
+description: Claim and implement a task following Research and Plan → Implement workflow
+---
+
+# Implement Task Command
+
+Claim and implement the next available task from the backlog using the Trellis task management system with the Research and Plan → Implement workflow.
+
+## Goal
+
+Automatically claim the highest-priority available task and implement it following project standards, with comprehensive research, planning, and quality checks before marking complete.
+
+## Process
+
+### 1. Claim Next Available Task
+
+Command: `claim_task`
+
+#### Input
+
+`$ARGUMENTS` (optional) - Can specify:
+
+- Specific task ID to claim (e.g., "T-create-user-model")
+- `--worktree (worktree-path)` - Worktree identifier to stamp on claimed task (currently informational only)
+- `--scope (issue-id)` - Hierarchical scope for task filtering (P-, E-, F- prefixed)
+- `--force` - Bypass validation when claiming specific task (only with `taskId`)
+- Additional context or preferences
+
+#### Instructions
+
+Claims are made against the current working directory's task trellis system (tasks are managed in `.trellis` folder).
+
+### 2. Research and Planning Phase (MANDATORY)
+
+**Never skip research - understand before coding:**
+
+The research phase is critical for understanding the context and requirements before writing any code. During this phase:
+
+- **Read parent issues for context**: Use MCP `get_issue` to read the parent feature (if it has one) for additional context, specifications, and requirements that may not be fully detailed in the task description.
+- **Research**: Review the task requirements and related materials to identify key considerations, potential challenges, and relevant patterns or practices. Analyze the existing codebase for similar implementations or patterns. If necessary, perform external research via MCP tools or web searches.
+
+```
+📚 Research Phase for T-create-user-model
+
+1️⃣ Reading parent issues for context...
+   - `get_issue` for task's feature, epic, and project
+
+2️⃣ Using research and implementation planner subagent for comprehensive research and planning...
+
+✅ Research and planning complete. Implementing plan...
+```
+
+### 3. Implementation Phase
+
+**Execute the plan with progress updates:**
+
+The implementation phase is where the actual coding happens. During this phase:
+
+- **Write clean code**: Follow project conventions and best practices
+- **Run quality checks frequently**: Format, lint, and test after each major change
+- **Write tests alongside code**: Don't leave testing for the end
+- **Apply security measures**: Implement validation, sanitization, and protection as planned
+- **Handle errors gracefully**: Include proper error handling and user feedback
+
+### 4. Complete Task
+
+**Update task and provide summary:**
+
+The completion phase ensures the task is properly documented and marked as done. This phase includes:
+
+- **Verify all requirements met**: Check that the implementation satisfies the task description
+- **Confirm quality checks pass**: Ensure all tests, linting, and formatting are clean
+- **Write meaningful summary**: Describe what was implemented and any important decisions
+- **List all changed files**: Document what was created or modified
+- **Update task status**: Use MCP to mark the task as complete
+- **Note any follow-up needed**: Identify if additional tasks should be created
+
+Use MCP `complete_task` with:
+
+- Task ID
+- Summary of work done
+- List of files changed
+
+Example for a database model task:
+
+```
+✅ Completing task: T-create-user-model
+
+Summary:
+Implemented User model with all required fields including secure password
+hashing, email validation, and unique constraints. Added comprehensive
+test coverage and database migrations. Password hashing uses bcrypt with 12
+rounds for security. Email validation includes regex pattern and uniqueness
+constraints. All tests passing with 100% coverage.
+
+Files changed:
+- models/User.js (new) - User model with validation methods
+- models/index.js (modified) - Added User export
+- migrations/001_create_users.sql (new) - Database schema
+- tests/models/User.test.js (new) - Comprehensive test suite
+- package.json (modified) - Added bcrypt dependency
+
+✅ Task completed and moved to done folder!
+```
+
+### 5. Next Steps
+
+**Provide clear next actions:**
+
+```
+🎯 Task Complete: T-create-user-model
+```
+
+**STOP!** - Do not proceed. Complete one task and one task only. Do not implement another task.
+
+### During Research and Planning Phase
+
+```
+⚠️ Research issue: Cannot find existing model patterns
+
+Attempting alternative approaches:
+- Checking documentation...
+- Searching for examples...
+- Using web search for best practices...
+
+[If still stuck]
+❓ Need clarification:
+The project doesn't seem to have existing models.
+Should I:
+A) Create the first model and establish patterns
+B) Check if models are in a different location
+C) Use a different approach (raw SQL, different ORM)
+```
+
+## Security & Performance Principles
+
+### Security Always:
+
+- **Validate ALL inputs** - Never trust user data
+- **Use secure defaults** - Fail closed, not open
+- **Parameterized queries** - Never concatenate SQL/queries
+- **Secure random** - Use cryptographically secure generators
+- **Least privilege** - Request minimum permissions needed
+- **Error handling** - Don't expose internal details
+
+## Quality Standards
+
+During implementation, ensure:
+
+- **Research First**: Never skip research phase
+- **Test Coverage**: Write tests in same task
+- **Security**: Validate all inputs
+- **Documentation**: Comment complex logic
+- **Quality Checks**: All must pass before completion
+
+## Workflow Guidelines
+
+- Always follow Research and Plan → Implement
+- Run quality checks after each major change
+- Write tests alongside implementation
+- Commit only when all checks pass
+
+<rules>
+  <critical>ALWAYS follow Research and Plan → Implement workflow</critical>
+  <critical>NEVER skip quality checks before completing task</critical>
+  <critical>All tests must pass before marking task complete</critical>
+  <important>Search codebase for patterns before implementing</important>
+  <important>Write tests in the same task as implementation</important>
+  <important>Apply security best practices to all code</important>
+</rules>