diff --git a/README.md b/README.md
index e93329b..5d58eee 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@

- # NixOS Home Lab Infrastructure
+# NixOS Home Lab Infrastructure
[](https://nixos.org/)
[](https://nixos.wiki/wiki/Flakes)
@@ -11,7 +11,8 @@
Modular NixOS flake configuration for multi-machine home lab infrastructure. Features declarative system configuration, centralized user management, and scalable service deployment across development workstations and server infrastructure.
# Vibe DevSecOpsing with claude-sonnet 4 and github-copilot
-A project about handling pets. If you want to handle sheep, look elsewhere :-)
+
+A project about handling pets. If you want to handle sheep, look elsewhere :-)
## Quick Start
@@ -33,12 +34,14 @@ sudo nixos-rebuild switch --flake .#
## Architecture Overview
### Machine Types
+
- **Development Workstation** - High-performance development environment with desktop environments
- **File Server** - ZFS storage with NFS services and media management
- **Application Server** - Containerized services (Git hosting, media server, web applications)
- **Reverse Proxy** - External gateway with SSL termination and service routing
### Technology Stack
+
- **Base OS**:
NixOS 25.05 with Nix Flakes
- **Configuration**: Modular, declarative system configuration
- **Virtualization**: Incus containers, Libvirt/QEMU VMs, Podman containers
@@ -75,18 +78,21 @@ Home-lab/
### Modular Design
+
- **Single Responsibility**: Each module handles one aspect of system configuration
- **Composable**: Modules can be mixed and matched per machine requirements
- **Testable**: Individual modules can be validated independently
- **Documented**: Clear documentation for module purpose and configuration
### User Management Strategy
+
- **Role-based Users**: Separate users for desktop vs server administration
- **Centralized Configuration**: Consistent user setup across all machines
- **Security Focus**: SSH key management and privilege separation
- **Literate Dotfiles**: Org-mode documentation for complex configurations
### Network Architecture
+
- **Mesh VPN**: Tailscale for secure inter-machine communication
- **Service Discovery**: Centralized hostname resolution
- **Firewall Management**: Service-specific port configuration
@@ -95,6 +101,7 @@ Home-lab/
## Development Workflow
### Local Testing
+
```bash
# Validate configuration syntax
nix flake check
@@ -110,12 +117,14 @@ sudo nixos-rebuild switch --flake .#
```
### Git Workflow
+
1. **Feature Branch**: Create branch for configuration changes
2. **Local Testing**: Validate changes with `nixos-rebuild test`
3. **Pull Request**: Submit changes for review
4. **Deploy**: Apply configuration to target machines
### Remote Deployment
+
- **SSH-based**: Remote deployment via secure shell
- **Atomic Updates**: Complete success or automatic rollback
- **Health Checks**: Service validation after deployment
@@ -124,6 +133,7 @@ sudo nixos-rebuild switch --flake .#
## Service Architecture
### Core Services
+
- **Git Hosting**: Self-hosted Git with CI/CD capabilities
- **Media Server**: Streaming with transcoding support
- **File Storage**: NFS network storage with ZFS snapshots
@@ -131,12 +141,14 @@ sudo nixos-rebuild switch --flake .#
- **Container Platform**: Podman for containerized applications
### Service Discovery
+
- **Internal DNS**: Tailscale for mesh network resolution
- **External DNS**: Public domain with SSL certificates
- **Service Mesh**: Inter-service communication via secure network
- **Load Balancing**: Traffic distribution and failover
### Data Management
+
- **ZFS Storage**: Copy-on-write filesystem with snapshots
- **Network Shares**: NFS for cross-machine file access
- **Backup Strategy**: Automated snapshots and external backup
@@ -145,18 +157,21 @@ sudo nixos-rebuild switch --flake .#
## Security Model
### Network Security
+
- **VPN Mesh**: All inter-machine traffic via Tailscale
- **Firewall Rules**: Service-specific port restrictions
- **SSH Hardening**: Key-based authentication only
- **Fail2ban**: Automated intrusion prevention
### User Security
+
- **Role Separation**: Administrative vs daily-use accounts
- **Key Management**: Centralized SSH key distribution
- **Privilege Escalation**: Sudo access only where needed
- **Service Accounts**: Dedicated accounts for automated services
### Infrastructure Security
+
- **Configuration as Code**: All changes tracked in version control
- **Atomic Deployments**: Rollback capability for failed changes
- **Secret Management**: Encrypted secrets with controlled access
@@ -165,12 +180,14 @@ sudo nixos-rebuild switch --flake .#
## Testing Strategy
### Automated Testing
+
- **Syntax Validation**: Nix flake syntax checking
- **Build Testing**: Configuration build verification
- **Module Testing**: Individual component validation
- **Integration Testing**: Full system deployment tests
### Manual Testing
+
- **Boot Validation**: System startup verification
- **Service Health**: Application functionality checks
- **Network Connectivity**: Inter-service communication tests
@@ -179,6 +196,7 @@ sudo nixos-rebuild switch --flake .#
## Deployment Status
### Infrastructure Maturity
+
- ✅ **Multi-machine Configuration**: 4 machines deployed
- ✅ **Service Integration**: Git hosting, media server, file storage
- ✅ **Network Mesh**: Secure VPN with service discovery
@@ -186,6 +204,7 @@ sudo nixos-rebuild switch --flake .#
- ✅ **Centralized Management**: Single repository for all infrastructure
### Current Capabilities
+
- **Development Environment**: Full IDE setup with multiple desktop options
- **File Services**: Network storage with 900GB+ media library
- **Git Hosting**: Self-hosted with external access
@@ -199,7 +218,6 @@ sudo nixos-rebuild switch --flake .#
- **[Branching Strategy](BRANCHING_STRATEGY.md)**: Git workflow and conventions
- **[AI Instructions](instruction.md)**: Agent guidance for system management
-
## License
MIT License - see [LICENSE](LICENSE) for details.
diff --git a/packages/.cursor/mcp.json b/packages/.cursor/mcp.json
new file mode 100644
index 0000000..7e49eb3
--- /dev/null
+++ b/packages/.cursor/mcp.json
@@ -0,0 +1,23 @@
+{
+ "mcpServers": {
+ "task-master-ai": {
+ "command": "npx",
+ "args": [
+ "-y",
+ "--package=task-master-ai",
+ "task-master-ai"
+ ],
+ "env": {
+ "ANTHROPIC_API_KEY": "ANTHROPIC_API_KEY_HERE",
+ "PERPLEXITY_API_KEY": "PERPLEXITY_API_KEY_HERE",
+ "OPENAI_API_KEY": "OPENAI_API_KEY_HERE",
+ "GOOGLE_API_KEY": "GOOGLE_API_KEY_HERE",
+ "XAI_API_KEY": "XAI_API_KEY_HERE",
+ "OPENROUTER_API_KEY": "OPENROUTER_API_KEY_HERE",
+ "MISTRAL_API_KEY": "MISTRAL_API_KEY_HERE",
+ "AZURE_OPENAI_API_KEY": "AZURE_OPENAI_API_KEY_HERE",
+ "OLLAMA_API_KEY": "OLLAMA_API_KEY_HERE"
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/packages/.cursor/rules/cursor_rules.mdc b/packages/.cursor/rules/cursor_rules.mdc
new file mode 100644
index 0000000..7dfae3d
--- /dev/null
+++ b/packages/.cursor/rules/cursor_rules.mdc
@@ -0,0 +1,53 @@
+---
+description: Guidelines for creating and maintaining Cursor rules to ensure consistency and effectiveness.
+globs: .cursor/rules/*.mdc
+alwaysApply: true
+---
+
+- **Required Rule Structure:**
+ ```markdown
+ ---
+ description: Clear, one-line description of what the rule enforces
+ globs: path/to/files/*.ext, other/path/**/*
+ alwaysApply: boolean
+ ---
+
+ - **Main Points in Bold**
+ - Sub-points with details
+ - Examples and explanations
+ ```
+
+- **File References:**
+ - Use `[filename](mdc:path/to/file)` ([filename](mdc:filename)) to reference files
+ - Example: [prisma.mdc](mdc:.cursor/rules/prisma.mdc) for rule references
+ - Example: [schema.prisma](mdc:prisma/schema.prisma) for code references
+
+- **Code Examples:**
+ - Use language-specific code blocks
+ ```typescript
+ // ✅ DO: Show good examples
+ const goodExample = true;
+
+ // ❌ DON'T: Show anti-patterns
+ const badExample = false;
+ ```
+
+- **Rule Content Guidelines:**
+ - Start with high-level overview
+ - Include specific, actionable requirements
+ - Show examples of correct implementation
+ - Reference existing code when possible
+ - Keep rules DRY by referencing other rules
+
+- **Rule Maintenance:**
+ - Update rules when new patterns emerge
+ - Add examples from actual codebase
+ - Remove outdated patterns
+ - Cross-reference related rules
+
+- **Best Practices:**
+ - Use bullet points for clarity
+ - Keep descriptions concise
+ - Include both DO and DON'T examples
+ - Reference actual code over theoretical examples
+ - Use consistent formatting across rules
\ No newline at end of file
diff --git a/packages/.cursor/rules/dev_workflow.mdc b/packages/.cursor/rules/dev_workflow.mdc
new file mode 100644
index 0000000..3333ce9
--- /dev/null
+++ b/packages/.cursor/rules/dev_workflow.mdc
@@ -0,0 +1,412 @@
+---
+description: Guide for using Taskmaster to manage task-driven development workflows
+globs: **/*
+alwaysApply: true
+---
+
+# Taskmaster Development Workflow
+
+This guide outlines the standard process for using Taskmaster to manage software development projects. It is written as a set of instructions for you, the AI agent.
+
+- **Your Default Stance**: For most projects, the user can work directly within the `master` task context. Your initial actions should operate on this default context unless a clear pattern for multi-context work emerges.
+- **Your Goal**: Your role is to elevate the user's workflow by intelligently introducing advanced features like **Tagged Task Lists** when you detect the appropriate context. Do not force tags on the user; suggest them as a helpful solution to a specific need.
+
+## The Basic Loop
+The fundamental development cycle you will facilitate is:
+1. **`list`**: Show the user what needs to be done.
+2. **`next`**: Help the user decide what to work on.
+3. **`show `**: Provide details for a specific task.
+4. **`expand `**: Break down a complex task into smaller, manageable subtasks.
+5. **Implement**: The user writes the code and tests.
+6. **`update-subtask`**: Log progress and findings on behalf of the user.
+7. **`set-status`**: Mark tasks and subtasks as `done` as work is completed.
+8. **Repeat**.
+
+All your standard command executions should operate on the user's current task context, which defaults to `master`.
+
+---
+
+## Standard Development Workflow Process
+
+### Simple Workflow (Default Starting Point)
+
+For new projects or when users are getting started, operate within the `master` tag context:
+
+- Start new projects by running `initialize_project` tool / `task-master init` or `parse_prd` / `task-master parse-prd --input=''` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to generate initial tasks.json with tagged structure
+- Begin coding sessions with `get_tasks` / `task-master list` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to see current tasks, status, and IDs
+- Determine the next task to work on using `next_task` / `task-master next` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc))
+- Analyze task complexity with `analyze_project_complexity` / `task-master analyze-complexity --research` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) before breaking down tasks
+- Review complexity report using `complexity_report` / `task-master complexity-report` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc))
+- Select tasks based on dependencies (all marked 'done'), priority level, and ID order
+- View specific task details using `get_task` / `task-master show ` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to understand implementation requirements
+- Break down complex tasks using `expand_task` / `task-master expand --id= --force --research` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) with appropriate flags like `--force` (to replace existing subtasks) and `--research`
+- Implement code following task details, dependencies, and project standards
+- Mark completed tasks with `set_task_status` / `task-master set-status --id= --status=done` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc))
+- Update dependent tasks when implementation differs from original plan using `update` / `task-master update --from= --prompt="..."` or `update_task` / `task-master update-task --id= --prompt="..."` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc))
+
+---
+
+## Leveling Up: Agent-Led Multi-Context Workflows
+
+While the basic workflow is powerful, your primary opportunity to add value is by identifying when to introduce **Tagged Task Lists**. These patterns are your tools for creating a more organized and efficient development environment for the user, especially if you detect agentic or parallel development happening across the same session.
+
+**Critical Principle**: Most users should never see a difference in their experience. Only introduce advanced workflows when you detect clear indicators that the project has evolved beyond simple task management.
+
+### When to Introduce Tags: Your Decision Patterns
+
+Here are the patterns to look for. When you detect one, you should propose the corresponding workflow to the user.
+
+#### Pattern 1: Simple Git Feature Branching
+This is the most common and direct use case for tags.
+
+- **Trigger**: The user creates a new git branch (e.g., `git checkout -b feature/user-auth`).
+- **Your Action**: Propose creating a new tag that mirrors the branch name to isolate the feature's tasks from `master`.
+- **Your Suggested Prompt**: *"I see you've created a new branch named 'feature/user-auth'. To keep all related tasks neatly organized and separate from your main list, I can create a corresponding task tag for you. This helps prevent merge conflicts in your `tasks.json` file later. Shall I create the 'feature-user-auth' tag?"*
+- **Tool to Use**: `task-master add-tag --from-branch`
+
+#### Pattern 2: Team Collaboration
+- **Trigger**: The user mentions working with teammates (e.g., "My teammate Alice is handling the database schema," or "I need to review Bob's work on the API.").
+- **Your Action**: Suggest creating a separate tag for the user's work to prevent conflicts with shared master context.
+- **Your Suggested Prompt**: *"Since you're working with Alice, I can create a separate task context for your work to avoid conflicts. This way, Alice can continue working with the master list while you have your own isolated context. When you're ready to merge your work, we can coordinate the tasks back to master. Shall I create a tag for your current work?"*
+- **Tool to Use**: `task-master add-tag my-work --copy-from-current --description="My tasks while collaborating with Alice"`
+
+#### Pattern 3: Experiments or Risky Refactors
+- **Trigger**: The user wants to try something that might not be kept (e.g., "I want to experiment with switching our state management library," or "Let's refactor the old API module, but I want to keep the current tasks as a reference.").
+- **Your Action**: Propose creating a sandboxed tag for the experimental work.
+- **Your Suggested Prompt**: *"This sounds like a great experiment. To keep these new tasks separate from our main plan, I can create a temporary 'experiment-zustand' tag for this work. If we decide not to proceed, we can simply delete the tag without affecting the main task list. Sound good?"*
+- **Tool to Use**: `task-master add-tag experiment-zustand --description="Exploring Zustand migration"`
+
+#### Pattern 4: Large Feature Initiatives (PRD-Driven)
+This is a more structured approach for significant new features or epics.
+
+- **Trigger**: The user describes a large, multi-step feature that would benefit from a formal plan.
+- **Your Action**: Propose a comprehensive, PRD-driven workflow.
+- **Your Suggested Prompt**: *"This sounds like a significant new feature. To manage this effectively, I suggest we create a dedicated task context for it. Here's the plan: I'll create a new tag called 'feature-xyz', then we can draft a Product Requirements Document (PRD) together to scope the work. Once the PRD is ready, I'll automatically generate all the necessary tasks within that new tag. How does that sound?"*
+- **Your Implementation Flow**:
+ 1. **Create an empty tag**: `task-master add-tag feature-xyz --description "Tasks for the new XYZ feature"`. You can also start by creating a git branch if applicable, and then create the tag from that branch.
+ 2. **Collaborate & Create PRD**: Work with the user to create a detailed PRD file (e.g., `.taskmaster/docs/feature-xyz-prd.txt`).
+ 3. **Parse PRD into the new tag**: `task-master parse-prd .taskmaster/docs/feature-xyz-prd.txt --tag feature-xyz`
+ 4. **Prepare the new task list**: Follow up by suggesting `analyze-complexity` and `expand-all` for the newly created tasks within the `feature-xyz` tag.
+
+#### Pattern 5: Version-Based Development
+Tailor your approach based on the project maturity indicated by tag names.
+
+- **Prototype/MVP Tags** (`prototype`, `mvp`, `poc`, `v0.x`):
+ - **Your Approach**: Focus on speed and functionality over perfection
+ - **Task Generation**: Create tasks that emphasize "get it working" over "get it perfect"
+ - **Complexity Level**: Lower complexity, fewer subtasks, more direct implementation paths
+ - **Research Prompts**: Include context like "This is a prototype - prioritize speed and basic functionality over optimization"
+ - **Example Prompt Addition**: *"Since this is for the MVP, I'll focus on tasks that get core functionality working quickly rather than over-engineering."*
+
+- **Production/Mature Tags** (`v1.0+`, `production`, `stable`):
+ - **Your Approach**: Emphasize robustness, testing, and maintainability
+ - **Task Generation**: Include comprehensive error handling, testing, documentation, and optimization
+ - **Complexity Level**: Higher complexity, more detailed subtasks, thorough implementation paths
+ - **Research Prompts**: Include context like "This is for production - prioritize reliability, performance, and maintainability"
+ - **Example Prompt Addition**: *"Since this is for production, I'll ensure tasks include proper error handling, testing, and documentation."*
+
+### Advanced Workflow (Tag-Based & PRD-Driven)
+
+**When to Transition**: Recognize when the project has evolved (or has initiated a project which existing code) beyond simple task management. Look for these indicators:
+- User mentions teammates or collaboration needs
+- Project has grown to 15+ tasks with mixed priorities
+- User creates feature branches or mentions major initiatives
+- User initializes Taskmaster on an existing, complex codebase
+- User describes large features that would benefit from dedicated planning
+
+**Your Role in Transition**: Guide the user to a more sophisticated workflow that leverages tags for organization and PRDs for comprehensive planning.
+
+#### Master List Strategy (High-Value Focus)
+Once you transition to tag-based workflows, the `master` tag should ideally contain only:
+- **High-level deliverables** that provide significant business value
+- **Major milestones** and epic-level features
+- **Critical infrastructure** work that affects the entire project
+- **Release-blocking** items
+
+**What NOT to put in master**:
+- Detailed implementation subtasks (these go in feature-specific tags' parent tasks)
+- Refactoring work (create dedicated tags like `refactor-auth`)
+- Experimental features (use `experiment-*` tags)
+- Team member-specific tasks (use person-specific tags)
+
+#### PRD-Driven Feature Development
+
+**For New Major Features**:
+1. **Identify the Initiative**: When user describes a significant feature
+2. **Create Dedicated Tag**: `add_tag feature-[name] --description="[Feature description]"`
+3. **Collaborative PRD Creation**: Work with user to create comprehensive PRD in `.taskmaster/docs/feature-[name]-prd.txt`
+4. **Parse & Prepare**:
+ - `parse_prd .taskmaster/docs/feature-[name]-prd.txt --tag=feature-[name]`
+ - `analyze_project_complexity --tag=feature-[name] --research`
+ - `expand_all --tag=feature-[name] --research`
+5. **Add Master Reference**: Create a high-level task in `master` that references the feature tag
+
+**For Existing Codebase Analysis**:
+When users initialize Taskmaster on existing projects:
+1. **Codebase Discovery**: Use your native tools for producing deep context about the code base. You may use `research` tool with `--tree` and `--files` to collect up to date information using the existing architecture as context.
+2. **Collaborative Assessment**: Work with user to identify improvement areas, technical debt, or new features
+3. **Strategic PRD Creation**: Co-author PRDs that include:
+ - Current state analysis (based on your codebase research)
+ - Proposed improvements or new features
+ - Implementation strategy considering existing code
+4. **Tag-Based Organization**: Parse PRDs into appropriate tags (`refactor-api`, `feature-dashboard`, `tech-debt`, etc.)
+5. **Master List Curation**: Keep only the most valuable initiatives in master
+
+The parse-prd's `--append` flag enables the user to parse multple PRDs within tags or across tags. PRDs should be focused and the number of tasks they are parsed into should be strategically chosen relative to the PRD's complexity and level of detail.
+
+### Workflow Transition Examples
+
+**Example 1: Simple → Team-Based**
+```
+User: "Alice is going to help with the API work"
+Your Response: "Great! To avoid conflicts, I'll create a separate task context for your work. Alice can continue with the master list while you work in your own context. When you're ready to merge, we can coordinate the tasks back together."
+Action: add_tag my-api-work --copy-from-current --description="My API tasks while collaborating with Alice"
+```
+
+**Example 2: Simple → PRD-Driven**
+```
+User: "I want to add a complete user dashboard with analytics, user management, and reporting"
+Your Response: "This sounds like a major feature that would benefit from detailed planning. Let me create a dedicated context for this work and we can draft a PRD together to ensure we capture all requirements."
+Actions:
+1. add_tag feature-dashboard --description="User dashboard with analytics and management"
+2. Collaborate on PRD creation
+3. parse_prd dashboard-prd.txt --tag=feature-dashboard
+4. Add high-level "User Dashboard" task to master
+```
+
+**Example 3: Existing Project → Strategic Planning**
+```
+User: "I just initialized Taskmaster on my existing React app. It's getting messy and I want to improve it."
+Your Response: "Let me research your codebase to understand the current architecture, then we can create a strategic plan for improvements."
+Actions:
+1. research "Current React app architecture and improvement opportunities" --tree --files=src/
+2. Collaborate on improvement PRD based on findings
+3. Create tags for different improvement areas (refactor-components, improve-state-management, etc.)
+4. Keep only major improvement initiatives in master
+```
+
+---
+
+## Primary Interaction: MCP Server vs. CLI
+
+Taskmaster offers two primary ways to interact:
+
+1. **MCP Server (Recommended for Integrated Tools)**:
+ - For AI agents and integrated development environments (like Cursor), interacting via the **MCP server is the preferred method**.
+ - The MCP server exposes Taskmaster functionality through a set of tools (e.g., `get_tasks`, `add_subtask`).
+ - This method offers better performance, structured data exchange, and richer error handling compared to CLI parsing.
+ - Refer to [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) for details on the MCP architecture and available tools.
+ - A comprehensive list and description of MCP tools and their corresponding CLI commands can be found in [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc).
+ - **Restart the MCP server** if core logic in `scripts/modules` or MCP tool/direct function definitions change.
+ - **Note**: MCP tools fully support tagged task lists with complete tag management capabilities.
+
+2. **`task-master` CLI (For Users & Fallback)**:
+ - The global `task-master` command provides a user-friendly interface for direct terminal interaction.
+ - It can also serve as a fallback if the MCP server is inaccessible or a specific function isn't exposed via MCP.
+ - Install globally with `npm install -g task-master-ai` or use locally via `npx task-master-ai ...`.
+ - The CLI commands often mirror the MCP tools (e.g., `task-master list` corresponds to `get_tasks`).
+ - Refer to [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc) for a detailed command reference.
+ - **Tagged Task Lists**: CLI fully supports the new tagged system with seamless migration.
+
+## How the Tag System Works (For Your Reference)
+
+- **Data Structure**: Tasks are organized into separate contexts (tags) like "master", "feature-branch", or "v2.0".
+- **Silent Migration**: Existing projects automatically migrate to use a "master" tag with zero disruption.
+- **Context Isolation**: Tasks in different tags are completely separate. Changes in one tag do not affect any other tag.
+- **Manual Control**: The user is always in control. There is no automatic switching. You facilitate switching by using `use-tag `.
+- **Full CLI & MCP Support**: All tag management commands are available through both the CLI and MCP tools for you to use. Refer to [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc) for a full command list.
+
+---
+
+## Task Complexity Analysis
+
+- Run `analyze_project_complexity` / `task-master analyze-complexity --research` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) for comprehensive analysis
+- Review complexity report via `complexity_report` / `task-master complexity-report` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) for a formatted, readable version.
+- Focus on tasks with highest complexity scores (8-10) for detailed breakdown
+- Use analysis results to determine appropriate subtask allocation
+- Note that reports are automatically used by the `expand_task` tool/command
+
+## Task Breakdown Process
+
+- Use `expand_task` / `task-master expand --id=`. It automatically uses the complexity report if found, otherwise generates default number of subtasks.
+- Use `--num=` to specify an explicit number of subtasks, overriding defaults or complexity report recommendations.
+- Add `--research` flag to leverage Perplexity AI for research-backed expansion.
+- Add `--force` flag to clear existing subtasks before generating new ones (default is to append).
+- Use `--prompt=""` to provide additional context when needed.
+- Review and adjust generated subtasks as necessary.
+- Use `expand_all` tool or `task-master expand --all` to expand multiple pending tasks at once, respecting flags like `--force` and `--research`.
+- If subtasks need complete replacement (regardless of the `--force` flag on `expand`), clear them first with `clear_subtasks` / `task-master clear-subtasks --id=`.
+
+## Implementation Drift Handling
+
+- When implementation differs significantly from planned approach
+- When future tasks need modification due to current implementation choices
+- When new dependencies or requirements emerge
+- Use `update` / `task-master update --from= --prompt='\nUpdate context...' --research` to update multiple future tasks.
+- Use `update_task` / `task-master update-task --id= --prompt='\nUpdate context...' --research` to update a single specific task.
+
+## Task Status Management
+
+- Use 'pending' for tasks ready to be worked on
+- Use 'done' for completed and verified tasks
+- Use 'deferred' for postponed tasks
+- Add custom status values as needed for project-specific workflows
+
+## Task Structure Fields
+
+- **id**: Unique identifier for the task (Example: `1`, `1.1`)
+- **title**: Brief, descriptive title (Example: `"Initialize Repo"`)
+- **description**: Concise summary of what the task involves (Example: `"Create a new repository, set up initial structure."`)
+- **status**: Current state of the task (Example: `"pending"`, `"done"`, `"deferred"`)
+- **dependencies**: IDs of prerequisite tasks (Example: `[1, 2.1]`)
+ - Dependencies are displayed with status indicators (✅ for completed, ⏱️ for pending)
+ - This helps quickly identify which prerequisite tasks are blocking work
+- **priority**: Importance level (Example: `"high"`, `"medium"`, `"low"`)
+- **details**: In-depth implementation instructions (Example: `"Use GitHub client ID/secret, handle callback, set session token."`)
+- **testStrategy**: Verification approach (Example: `"Deploy and call endpoint to confirm 'Hello World' response."`)
+- **subtasks**: List of smaller, more specific tasks (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`)
+- Refer to task structure details (previously linked to `tasks.mdc`).
+
+## Configuration Management (Updated)
+
+Taskmaster configuration is managed through two main mechanisms:
+
+1. **`.taskmaster/config.json` File (Primary):**
+ * Located in the project root directory.
+ * Stores most configuration settings: AI model selections (main, research, fallback), parameters (max tokens, temperature), logging level, default subtasks/priority, project name, etc.
+ * **Tagged System Settings**: Includes `global.defaultTag` (defaults to "master") and `tags` section for tag management configuration.
+ * **Managed via `task-master models --setup` command.** Do not edit manually unless you know what you are doing.
+ * **View/Set specific models via `task-master models` command or `models` MCP tool.**
+ * Created automatically when you run `task-master models --setup` for the first time or during tagged system migration.
+
+2. **Environment Variables (`.env` / `mcp.json`):**
+ * Used **only** for sensitive API keys and specific endpoint URLs.
+ * Place API keys (one per provider) in a `.env` file in the project root for CLI usage.
+ * For MCP/Cursor integration, configure these keys in the `env` section of `.cursor/mcp.json`.
+ * Available keys/variables: See `assets/env.example` or the Configuration section in the command reference (previously linked to `taskmaster.mdc`).
+
+3. **`.taskmaster/state.json` File (Tagged System State):**
+ * Tracks current tag context and migration status.
+ * Automatically created during tagged system migration.
+ * Contains: `currentTag`, `lastSwitched`, `migrationNoticeShown`.
+
+**Important:** Non-API key settings (like model selections, `MAX_TOKENS`, `TASKMASTER_LOG_LEVEL`) are **no longer configured via environment variables**. Use the `task-master models` command (or `--setup` for interactive configuration) or the `models` MCP tool.
+**If AI commands FAIL in MCP** verify that the API key for the selected provider is present in the `env` section of `.cursor/mcp.json`.
+**If AI commands FAIL in CLI** verify that the API key for the selected provider is present in the `.env` file in the root of the project.
+
+## Determining the Next Task
+
+- Run `next_task` / `task-master next` to show the next task to work on.
+- The command identifies tasks with all dependencies satisfied
+- Tasks are prioritized by priority level, dependency count, and ID
+- The command shows comprehensive task information including:
+ - Basic task details and description
+ - Implementation details
+ - Subtasks (if they exist)
+ - Contextual suggested actions
+- Recommended before starting any new development work
+- Respects your project's dependency structure
+- Ensures tasks are completed in the appropriate sequence
+- Provides ready-to-use commands for common task actions
+
+## Viewing Specific Task Details
+
+- Run `get_task` / `task-master show ` to view a specific task.
+- Use dot notation for subtasks: `task-master show 1.2` (shows subtask 2 of task 1)
+- Displays comprehensive information similar to the next command, but for a specific task
+- For parent tasks, shows all subtasks and their current status
+- For subtasks, shows parent task information and relationship
+- Provides contextual suggested actions appropriate for the specific task
+- Useful for examining task details before implementation or checking status
+
+## Managing Task Dependencies
+
+- Use `add_dependency` / `task-master add-dependency --id= --depends-on=` to add a dependency.
+- Use `remove_dependency` / `task-master remove-dependency --id= --depends-on=` to remove a dependency.
+- The system prevents circular dependencies and duplicate dependency entries
+- Dependencies are checked for existence before being added or removed
+- Task files are automatically regenerated after dependency changes
+- Dependencies are visualized with status indicators in task listings and files
+
+## Task Reorganization
+
+- Use `move_task` / `task-master move --from= --to=` to move tasks or subtasks within the hierarchy
+- This command supports several use cases:
+ - Moving a standalone task to become a subtask (e.g., `--from=5 --to=7`)
+ - Moving a subtask to become a standalone task (e.g., `--from=5.2 --to=7`)
+ - Moving a subtask to a different parent (e.g., `--from=5.2 --to=7.3`)
+ - Reordering subtasks within the same parent (e.g., `--from=5.2 --to=5.4`)
+ - Moving a task to a new, non-existent ID position (e.g., `--from=5 --to=25`)
+ - Moving multiple tasks at once using comma-separated IDs (e.g., `--from=10,11,12 --to=16,17,18`)
+- The system includes validation to prevent data loss:
+ - Allows moving to non-existent IDs by creating placeholder tasks
+ - Prevents moving to existing task IDs that have content (to avoid overwriting)
+ - Validates source tasks exist before attempting to move them
+- The system maintains proper parent-child relationships and dependency integrity
+- Task files are automatically regenerated after the move operation
+- This provides greater flexibility in organizing and refining your task structure as project understanding evolves
+- This is especially useful when dealing with potential merge conflicts arising from teams creating tasks on separate branches. Solve these conflicts very easily by moving your tasks and keeping theirs.
+
+## Iterative Subtask Implementation
+
+Once a task has been broken down into subtasks using `expand_task` or similar methods, follow this iterative process for implementation:
+
+1. **Understand the Goal (Preparation):**
+ * Use `get_task` / `task-master show ` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to thoroughly understand the specific goals and requirements of the subtask.
+
+2. **Initial Exploration & Planning (Iteration 1):**
+ * This is the first attempt at creating a concrete implementation plan.
+ * Explore the codebase to identify the precise files, functions, and even specific lines of code that will need modification.
+ * Determine the intended code changes (diffs) and their locations.
+ * Gather *all* relevant details from this exploration phase.
+
+3. **Log the Plan:**
+ * Run `update_subtask` / `task-master update-subtask --id= --prompt=''`.
+ * Provide the *complete and detailed* findings from the exploration phase in the prompt. Include file paths, line numbers, proposed diffs, reasoning, and any potential challenges identified. Do not omit details. The goal is to create a rich, timestamped log within the subtask's `details`.
+
+4. **Verify the Plan:**
+ * Run `get_task` / `task-master show ` again to confirm that the detailed implementation plan has been successfully appended to the subtask's details.
+
+5. **Begin Implementation:**
+ * Set the subtask status using `set_task_status` / `task-master set-status --id= --status=in-progress`.
+ * Start coding based on the logged plan.
+
+6. **Refine and Log Progress (Iteration 2+):**
+ * As implementation progresses, you will encounter challenges, discover nuances, or confirm successful approaches.
+ * **Before appending new information**: Briefly review the *existing* details logged in the subtask (using `get_task` or recalling from context) to ensure the update adds fresh insights and avoids redundancy.
+ * **Regularly** use `update_subtask` / `task-master update-subtask --id= --prompt='\n- What worked...\n- What didn't work...'` to append new findings.
+ * **Crucially, log:**
+ * What worked ("fundamental truths" discovered).
+ * What didn't work and why (to avoid repeating mistakes).
+ * Specific code snippets or configurations that were successful.
+ * Decisions made, especially if confirmed with user input.
+ * Any deviations from the initial plan and the reasoning.
+ * The objective is to continuously enrich the subtask's details, creating a log of the implementation journey that helps the AI (and human developers) learn, adapt, and avoid repeating errors.
+
+7. **Review & Update Rules (Post-Implementation):**
+ * Once the implementation for the subtask is functionally complete, review all code changes and the relevant chat history.
+ * Identify any new or modified code patterns, conventions, or best practices established during the implementation.
+ * Create new or update existing rules following internal guidelines (previously linked to `cursor_rules.mdc` and `self_improve.mdc`).
+
+8. **Mark Task Complete:**
+ * After verifying the implementation and updating any necessary rules, mark the subtask as completed: `set_task_status` / `task-master set-status --id= --status=done`.
+
+9. **Commit Changes (If using Git):**
+ * Stage the relevant code changes and any updated/new rule files (`git add .`).
+ * Craft a comprehensive Git commit message summarizing the work done for the subtask, including both code implementation and any rule adjustments.
+ * Execute the commit command directly in the terminal (e.g., `git commit -m 'feat(module): Implement feature X for subtask \n\n- Details about changes...\n- Updated rule Y for pattern Z'`).
+ * Consider if a Changeset is needed according to internal versioning guidelines (previously linked to `changeset.mdc`). If so, run `npm run changeset`, stage the generated file, and amend the commit or create a new one.
+
+10. **Proceed to Next Subtask:**
+ * Identify the next subtask (e.g., using `next_task` / `task-master next`).
+
+## Code Analysis & Refactoring Techniques
+
+- **Top-Level Function Search**:
+ - Useful for understanding module structure or planning refactors.
+ - Use grep/ripgrep to find exported functions/constants:
+ `rg "export (async function|function|const) \w+"` or similar patterns.
+ - Can help compare functions between files during migrations or identify potential naming conflicts.
+
+---
+*This workflow provides a general guideline. Adapt it based on your specific project needs and team practices.*
\ No newline at end of file
diff --git a/packages/.cursor/rules/self_improve.mdc b/packages/.cursor/rules/self_improve.mdc
new file mode 100644
index 0000000..40b31b6
--- /dev/null
+++ b/packages/.cursor/rules/self_improve.mdc
@@ -0,0 +1,72 @@
+---
+description: Guidelines for continuously improving Cursor rules based on emerging code patterns and best practices.
+globs: **/*
+alwaysApply: true
+---
+
+- **Rule Improvement Triggers:**
+ - New code patterns not covered by existing rules
+ - Repeated similar implementations across files
+ - Common error patterns that could be prevented
+ - New libraries or tools being used consistently
+ - Emerging best practices in the codebase
+
+- **Analysis Process:**
+ - Compare new code with existing rules
+ - Identify patterns that should be standardized
+ - Look for references to external documentation
+ - Check for consistent error handling patterns
+ - Monitor test patterns and coverage
+
+- **Rule Updates:**
+ - **Add New Rules When:**
+ - A new technology/pattern is used in 3+ files
+ - Common bugs could be prevented by a rule
+ - Code reviews repeatedly mention the same feedback
+ - New security or performance patterns emerge
+
+ - **Modify Existing Rules When:**
+ - Better examples exist in the codebase
+ - Additional edge cases are discovered
+ - Related rules have been updated
+ - Implementation details have changed
+
+- **Example Pattern Recognition:**
+ ```typescript
+ // If you see repeated patterns like:
+ const data = await prisma.user.findMany({
+ select: { id: true, email: true },
+ where: { status: 'ACTIVE' }
+ });
+
+ // Consider adding to [prisma.mdc](mdc:.cursor/rules/prisma.mdc):
+ // - Standard select fields
+ // - Common where conditions
+ // - Performance optimization patterns
+ ```
+
+- **Rule Quality Checks:**
+ - Rules should be actionable and specific
+ - Examples should come from actual code
+ - References should be up to date
+ - Patterns should be consistently enforced
+
+- **Continuous Improvement:**
+ - Monitor code review comments
+ - Track common development questions
+ - Update rules after major refactors
+ - Add links to relevant documentation
+ - Cross-reference related rules
+
+- **Rule Deprecation:**
+ - Mark outdated patterns as deprecated
+ - Remove rules that no longer apply
+ - Update references to deprecated rules
+ - Document migration paths for old patterns
+
+- **Documentation Updates:**
+ - Keep examples synchronized with code
+ - Update references to external docs
+ - Maintain links between related rules
+ - Document breaking changes
+Follow [cursor_rules.mdc](mdc:.cursor/rules/cursor_rules.mdc) for proper rule formatting and structure.
diff --git a/packages/.cursor/rules/taskmaster.mdc b/packages/.cursor/rules/taskmaster.mdc
new file mode 100644
index 0000000..b4fe6df
--- /dev/null
+++ b/packages/.cursor/rules/taskmaster.mdc
@@ -0,0 +1,557 @@
+---
+description: Comprehensive reference for Taskmaster MCP tools and CLI commands.
+globs: **/*
+alwaysApply: true
+---
+# Taskmaster Tool & Command Reference
+
+This document provides a detailed reference for interacting with Taskmaster, covering both the recommended MCP tools, suitable for integrations like Cursor, and the corresponding `task-master` CLI commands, designed for direct user interaction or fallback.
+
+**Note:** For interacting with Taskmaster programmatically or via integrated tools, using the **MCP tools is strongly recommended** due to better performance, structured data, and error handling. The CLI commands serve as a user-friendly alternative and fallback.
+
+**Important:** Several MCP tools involve AI processing... The AI-powered tools include `parse_prd`, `analyze_project_complexity`, `update_subtask`, `update_task`, `update`, `expand_all`, `expand_task`, and `add_task`.
+
+**🏷️ Tagged Task Lists System:** Task Master now supports **tagged task lists** for multi-context task management. This allows you to maintain separate, isolated lists of tasks for different features, branches, or experiments. Existing projects are seamlessly migrated to use a default "master" tag. Most commands now support a `--tag ` flag to specify which context to operate on. If omitted, commands use the currently active tag.
+
+---
+
+## Initialization & Setup
+
+### 1. Initialize Project (`init`)
+
+* **MCP Tool:** `initialize_project`
+* **CLI Command:** `task-master init [options]`
+* **Description:** `Set up the basic Taskmaster file structure and configuration in the current directory for a new project.`
+* **Key CLI Options:**
+ * `--name `: `Set the name for your project in Taskmaster's configuration.`
+ * `--description `: `Provide a brief description for your project.`
+ * `--version `: `Set the initial version for your project, e.g., '0.1.0'.`
+ * `-y, --yes`: `Initialize Taskmaster quickly using default settings without interactive prompts.`
+* **Usage:** Run this once at the beginning of a new project.
+* **MCP Variant Description:** `Set up the basic Taskmaster file structure and configuration in the current directory for a new project by running the 'task-master init' command.`
+* **Key MCP Parameters/Options:**
+ * `projectName`: `Set the name for your project.` (CLI: `--name `)
+ * `projectDescription`: `Provide a brief description for your project.` (CLI: `--description `)
+ * `projectVersion`: `Set the initial version for your project, e.g., '0.1.0'.` (CLI: `--version `)
+ * `authorName`: `Author name.` (CLI: `--author `)
+ * `skipInstall`: `Skip installing dependencies. Default is false.` (CLI: `--skip-install`)
+ * `addAliases`: `Add shell aliases tm and taskmaster. Default is false.` (CLI: `--aliases`)
+ * `yes`: `Skip prompts and use defaults/provided arguments. Default is false.` (CLI: `-y, --yes`)
+* **Usage:** Run this once at the beginning of a new project, typically via an integrated tool like Cursor. Operates on the current working directory of the MCP server.
+* **Important:** Once complete, you *MUST* parse a prd in order to generate tasks. There will be no tasks files until then. The next step after initializing should be to create a PRD using the example PRD in .taskmaster/templates/example_prd.txt.
+* **Tagging:** Use the `--tag` option to parse the PRD into a specific, non-default tag context. If the tag doesn't exist, it will be created automatically. Example: `task-master parse-prd spec.txt --tag=new-feature`.
+
+### 2. Parse PRD (`parse_prd`)
+
+* **MCP Tool:** `parse_prd`
+* **CLI Command:** `task-master parse-prd [file] [options]`
+* **Description:** `Parse a Product Requirements Document, PRD, or text file with Taskmaster to automatically generate an initial set of tasks in tasks.json.`
+* **Key Parameters/Options:**
+ * `input`: `Path to your PRD or requirements text file that Taskmaster should parse for tasks.` (CLI: `[file]` positional or `-i, --input `)
+ * `output`: `Specify where Taskmaster should save the generated 'tasks.json' file. Defaults to '.taskmaster/tasks/tasks.json'.` (CLI: `-o, --output `)
+ * `numTasks`: `Approximate number of top-level tasks Taskmaster should aim to generate from the document.` (CLI: `-n, --num-tasks `)
+ * `force`: `Use this to allow Taskmaster to overwrite an existing 'tasks.json' without asking for confirmation.` (CLI: `-f, --force`)
+* **Usage:** Useful for bootstrapping a project from an existing requirements document.
+* **Notes:** Task Master will strictly adhere to any specific requirements mentioned in the PRD, such as libraries, database schemas, frameworks, tech stacks, etc., while filling in any gaps where the PRD isn't fully specified. Tasks are designed to provide the most direct implementation path while avoiding over-engineering.
+* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. If the user does not have a PRD, suggest discussing their idea and then use the example PRD in `.taskmaster/templates/example_prd.txt` as a template for creating the PRD based on their idea, for use with `parse-prd`.
+
+---
+
+## AI Model Configuration
+
+### 2. Manage Models (`models`)
+* **MCP Tool:** `models`
+* **CLI Command:** `task-master models [options]`
+* **Description:** `View the current AI model configuration or set specific models for different roles (main, research, fallback). Allows setting custom model IDs for Ollama and OpenRouter.`
+* **Key MCP Parameters/Options:**
+ * `setMain `: `Set the primary model ID for task generation/updates.` (CLI: `--set-main `)
+ * `setResearch `: `Set the model ID for research-backed operations.` (CLI: `--set-research `)
+ * `setFallback `: `Set the model ID to use if the primary fails.` (CLI: `--set-fallback `)
+ * `ollama `: `Indicates the set model ID is a custom Ollama model.` (CLI: `--ollama`)
+ * `openrouter `: `Indicates the set model ID is a custom OpenRouter model.` (CLI: `--openrouter`)
+ * `listAvailableModels `: `If true, lists available models not currently assigned to a role.` (CLI: No direct equivalent; CLI lists available automatically)
+ * `projectRoot `: `Optional. Absolute path to the project root directory.` (CLI: Determined automatically)
+* **Key CLI Options:**
+ * `--set-main `: `Set the primary model.`
+ * `--set-research `: `Set the research model.`
+ * `--set-fallback `: `Set the fallback model.`
+ * `--ollama`: `Specify that the provided model ID is for Ollama (use with --set-*).`
+ * `--openrouter`: `Specify that the provided model ID is for OpenRouter (use with --set-*). Validates against OpenRouter API.`
+ * `--bedrock`: `Specify that the provided model ID is for AWS Bedrock (use with --set-*).`
+ * `--setup`: `Run interactive setup to configure models, including custom Ollama/OpenRouter IDs.`
+* **Usage (MCP):** Call without set flags to get current config. Use `setMain`, `setResearch`, or `setFallback` with a valid model ID to update the configuration. Use `listAvailableModels: true` to get a list of unassigned models. To set a custom model, provide the model ID and set `ollama: true` or `openrouter: true`.
+* **Usage (CLI):** Run without flags to view current configuration and available models. Use set flags to update specific roles. Use `--setup` for guided configuration, including custom models. To set a custom model via flags, use `--set-=` along with either `--ollama` or `--openrouter`.
+* **Notes:** Configuration is stored in `.taskmaster/config.json` in the project root. This command/tool modifies that file. Use `listAvailableModels` or `task-master models` to see internally supported models. OpenRouter custom models are validated against their live API. Ollama custom models are not validated live.
+* **API note:** API keys for selected AI providers (based on their model) need to exist in the mcp.json file to be accessible in MCP context. The API keys must be present in the local .env file for the CLI to be able to read them.
+* **Model costs:** The costs in supported models are expressed in dollars. An input/output value of 3 is $3.00. A value of 0.8 is $0.80.
+* **Warning:** DO NOT MANUALLY EDIT THE .taskmaster/config.json FILE. Use the included commands either in the MCP or CLI format as needed. Always prioritize MCP tools when available and use the CLI as a fallback.
+
+---
+
+## Task Listing & Viewing
+
+### 3. Get Tasks (`get_tasks`)
+
+* **MCP Tool:** `get_tasks`
+* **CLI Command:** `task-master list [options]`
+* **Description:** `List your Taskmaster tasks, optionally filtering by status and showing subtasks.`
+* **Key Parameters/Options:**
+ * `status`: `Show only Taskmaster tasks matching this status (or multiple statuses, comma-separated), e.g., 'pending' or 'done,in-progress'.` (CLI: `-s, --status `)
+ * `withSubtasks`: `Include subtasks indented under their parent tasks in the list.` (CLI: `--with-subtasks`)
+ * `tag`: `Specify which tag context to list tasks from. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Get an overview of the project status, often used at the start of a work session.
+
+### 4. Get Next Task (`next_task`)
+
+* **MCP Tool:** `next_task`
+* **CLI Command:** `task-master next [options]`
+* **Description:** `Ask Taskmaster to show the next available task you can work on, based on status and completed dependencies.`
+* **Key Parameters/Options:**
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+ * `tag`: `Specify which tag context to use. Defaults to the current active tag.` (CLI: `--tag `)
+* **Usage:** Identify what to work on next according to the plan.
+
+### 5. Get Task Details (`get_task`)
+
+* **MCP Tool:** `get_task`
+* **CLI Command:** `task-master show [id] [options]`
+* **Description:** `Display detailed information for one or more specific Taskmaster tasks or subtasks by ID.`
+* **Key Parameters/Options:**
+ * `id`: `Required. The ID of the Taskmaster task (e.g., '15'), subtask (e.g., '15.2'), or a comma-separated list of IDs ('1,5,10.2') you want to view.` (CLI: `[id]` positional or `-i, --id `)
+ * `tag`: `Specify which tag context to get the task(s) from. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Understand the full details for a specific task. When multiple IDs are provided, a summary table is shown.
+* **CRITICAL INFORMATION** If you need to collect information from multiple tasks, use comma-separated IDs (i.e. 1,2,3) to receive an array of tasks. Do not needlessly get tasks one at a time if you need to get many as that is wasteful.
+
+---
+
+## Task Creation & Modification
+
+### 6. Add Task (`add_task`)
+
+* **MCP Tool:** `add_task`
+* **CLI Command:** `task-master add-task [options]`
+* **Description:** `Add a new task to Taskmaster by describing it; AI will structure it.`
+* **Key Parameters/Options:**
+ * `prompt`: `Required. Describe the new task you want Taskmaster to create, e.g., "Implement user authentication using JWT".` (CLI: `-p, --prompt `)
+ * `dependencies`: `Specify the IDs of any Taskmaster tasks that must be completed before this new one can start, e.g., '12,14'.` (CLI: `-d, --dependencies `)
+ * `priority`: `Set the priority for the new task: 'high', 'medium', or 'low'. Default is 'medium'.` (CLI: `--priority `)
+ * `research`: `Enable Taskmaster to use the research role for potentially more informed task creation.` (CLI: `-r, --research`)
+ * `tag`: `Specify which tag context to add the task to. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Quickly add newly identified tasks during development.
+* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
+
+### 7. Add Subtask (`add_subtask`)
+
+* **MCP Tool:** `add_subtask`
+* **CLI Command:** `task-master add-subtask [options]`
+* **Description:** `Add a new subtask to a Taskmaster parent task, or convert an existing task into a subtask.`
+* **Key Parameters/Options:**
+ * `id` / `parent`: `Required. The ID of the Taskmaster task that will be the parent.` (MCP: `id`, CLI: `-p, --parent `)
+ * `taskId`: `Use this if you want to convert an existing top-level Taskmaster task into a subtask of the specified parent.` (CLI: `-i, --task-id `)
+ * `title`: `Required if not using taskId. The title for the new subtask Taskmaster should create.` (CLI: `-t, --title `)
+ * `description`: `A brief description for the new subtask.` (CLI: `-d, --description `)
+ * `details`: `Provide implementation notes or details for the new subtask.` (CLI: `--details `)
+ * `dependencies`: `Specify IDs of other tasks or subtasks, e.g., '15' or '16.1', that must be done before this new subtask.` (CLI: `--dependencies `)
+ * `status`: `Set the initial status for the new subtask. Default is 'pending'.` (CLI: `-s, --status `)
+ * `skipGenerate`: `Prevent Taskmaster from automatically regenerating markdown task files after adding the subtask.` (CLI: `--skip-generate`)
+ * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Break down tasks manually or reorganize existing tasks.
+
+### 8. Update Tasks (`update`)
+
+* **MCP Tool:** `update`
+* **CLI Command:** `task-master update [options]`
+* **Description:** `Update multiple upcoming tasks in Taskmaster based on new context or changes, starting from a specific task ID.`
+* **Key Parameters/Options:**
+ * `from`: `Required. The ID of the first task Taskmaster should update. All tasks with this ID or higher that are not 'done' will be considered.` (CLI: `--from `)
+ * `prompt`: `Required. Explain the change or new context for Taskmaster to apply to the tasks, e.g., "We are now using React Query instead of Redux Toolkit for data fetching".` (CLI: `-p, --prompt `)
+ * `research`: `Enable Taskmaster to use the research role for more informed updates. Requires appropriate API key.` (CLI: `-r, --research`)
+ * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Handle significant implementation changes or pivots that affect multiple future tasks. Example CLI: `task-master update --from='18' --prompt='Switching to React Query.\nNeed to refactor data fetching...'`
+* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
+
+### 9. Update Task (`update_task`)
+
+* **MCP Tool:** `update_task`
+* **CLI Command:** `task-master update-task [options]`
+* **Description:** `Modify a specific Taskmaster task by ID, incorporating new information or changes. By default, this replaces the existing task details.`
+* **Key Parameters/Options:**
+ * `id`: `Required. The specific ID of the Taskmaster task, e.g., '15', you want to update.` (CLI: `-i, --id `)
+ * `prompt`: `Required. Explain the specific changes or provide the new information Taskmaster should incorporate into this task.` (CLI: `-p, --prompt `)
+ * `append`: `If true, appends the prompt content to the task's details with a timestamp, rather than replacing them. Behaves like update-subtask.` (CLI: `--append`)
+ * `research`: `Enable Taskmaster to use the research role for more informed updates. Requires appropriate API key.` (CLI: `-r, --research`)
+ * `tag`: `Specify which tag context the task belongs to. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Refine a specific task based on new understanding. Use `--append` to log progress without creating subtasks.
+* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
+
+### 10. Update Subtask (`update_subtask`)
+
+* **MCP Tool:** `update_subtask`
+* **CLI Command:** `task-master update-subtask [options]`
+* **Description:** `Append timestamped notes or details to a specific Taskmaster subtask without overwriting existing content. Intended for iterative implementation logging.`
+* **Key Parameters/Options:**
+ * `id`: `Required. The ID of the Taskmaster subtask, e.g., '5.2', to update with new information.` (CLI: `-i, --id `)
+ * `prompt`: `Required. The information, findings, or progress notes to append to the subtask's details with a timestamp.` (CLI: `-p, --prompt `)
+ * `research`: `Enable Taskmaster to use the research role for more informed updates. Requires appropriate API key.` (CLI: `-r, --research`)
+ * `tag`: `Specify which tag context the subtask belongs to. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Log implementation progress, findings, and discoveries during subtask development. Each update is timestamped and appended to preserve the implementation journey.
+* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
+
+### 11. Set Task Status (`set_task_status`)
+
+* **MCP Tool:** `set_task_status`
+* **CLI Command:** `task-master set-status [options]`
+* **Description:** `Update the status of one or more Taskmaster tasks or subtasks, e.g., 'pending', 'in-progress', 'done'.`
+* **Key Parameters/Options:**
+ * `id`: `Required. The ID(s) of the Taskmaster task(s) or subtask(s), e.g., '15', '15.2', or '16,17.1', to update.` (CLI: `-i, --id `)
+ * `status`: `Required. The new status to set, e.g., 'done', 'pending', 'in-progress', 'review', 'cancelled'.` (CLI: `-s, --status `)
+ * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Mark progress as tasks move through the development cycle.
+
+### 12. Remove Task (`remove_task`)
+
+* **MCP Tool:** `remove_task`
+* **CLI Command:** `task-master remove-task [options]`
+* **Description:** `Permanently remove a task or subtask from the Taskmaster tasks list.`
+* **Key Parameters/Options:**
+ * `id`: `Required. The ID of the Taskmaster task, e.g., '5', or subtask, e.g., '5.2', to permanently remove.` (CLI: `-i, --id `)
+ * `yes`: `Skip the confirmation prompt and immediately delete the task.` (CLI: `-y, --yes`)
+ * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Permanently delete tasks or subtasks that are no longer needed in the project.
+* **Notes:** Use with caution as this operation cannot be undone. Consider using 'blocked', 'cancelled', or 'deferred' status instead if you just want to exclude a task from active planning but keep it for reference. The command automatically cleans up dependency references in other tasks.
+
+---
+
+## Task Structure & Breakdown
+
+### 13. Expand Task (`expand_task`)
+
+* **MCP Tool:** `expand_task`
+* **CLI Command:** `task-master expand [options]`
+* **Description:** `Use Taskmaster's AI to break down a complex task into smaller, manageable subtasks. Appends subtasks by default.`
+* **Key Parameters/Options:**
+ * `id`: `The ID of the specific Taskmaster task you want to break down into subtasks.` (CLI: `-i, --id `)
+ * `num`: `Optional: Suggests how many subtasks Taskmaster should aim to create. Uses complexity analysis/defaults otherwise.` (CLI: `-n, --num `)
+ * `research`: `Enable Taskmaster to use the research role for more informed subtask generation. Requires appropriate API key.` (CLI: `-r, --research`)
+ * `prompt`: `Optional: Provide extra context or specific instructions to Taskmaster for generating the subtasks.` (CLI: `-p, --prompt `)
+ * `force`: `Optional: If true, clear existing subtasks before generating new ones. Default is false (append).` (CLI: `--force`)
+ * `tag`: `Specify which tag context the task belongs to. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Generate a detailed implementation plan for a complex task before starting coding. Automatically uses complexity report recommendations if available and `num` is not specified.
+* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
+
+### 14. Expand All Tasks (`expand_all`)
+
+* **MCP Tool:** `expand_all`
+* **CLI Command:** `task-master expand --all [options]` (Note: CLI uses the `expand` command with the `--all` flag)
+* **Description:** `Tell Taskmaster to automatically expand all eligible pending/in-progress tasks based on complexity analysis or defaults. Appends subtasks by default.`
+* **Key Parameters/Options:**
+ * `num`: `Optional: Suggests how many subtasks Taskmaster should aim to create per task.` (CLI: `-n, --num `)
+ * `research`: `Enable research role for more informed subtask generation. Requires appropriate API key.` (CLI: `-r, --research`)
+ * `prompt`: `Optional: Provide extra context for Taskmaster to apply generally during expansion.` (CLI: `-p, --prompt `)
+ * `force`: `Optional: If true, clear existing subtasks before generating new ones for each eligible task. Default is false (append).` (CLI: `--force`)
+ * `tag`: `Specify which tag context to expand. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Useful after initial task generation or complexity analysis to break down multiple tasks at once.
+* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
+
+### 15. Clear Subtasks (`clear_subtasks`)
+
+* **MCP Tool:** `clear_subtasks`
+* **CLI Command:** `task-master clear-subtasks [options]`
+* **Description:** `Remove all subtasks from one or more specified Taskmaster parent tasks.`
+* **Key Parameters/Options:**
+ * `id`: `The ID(s) of the Taskmaster parent task(s) whose subtasks you want to remove, e.g., '15' or '16,18'. Required unless using `all`.) (CLI: `-i, --id `)
+ * `all`: `Tell Taskmaster to remove subtasks from all parent tasks.` (CLI: `--all`)
+ * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Used before regenerating subtasks with `expand_task` if the previous breakdown needs replacement.
+
+### 16. Remove Subtask (`remove_subtask`)
+
+* **MCP Tool:** `remove_subtask`
+* **CLI Command:** `task-master remove-subtask [options]`
+* **Description:** `Remove a subtask from its Taskmaster parent, optionally converting it into a standalone task.`
+* **Key Parameters/Options:**
+ * `id`: `Required. The ID(s) of the Taskmaster subtask(s) to remove, e.g., '15.2' or '16.1,16.3'.` (CLI: `-i, --id `)
+ * `convert`: `If used, Taskmaster will turn the subtask into a regular top-level task instead of deleting it.` (CLI: `-c, --convert`)
+ * `skipGenerate`: `Prevent Taskmaster from automatically regenerating markdown task files after removing the subtask.` (CLI: `--skip-generate`)
+ * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Delete unnecessary subtasks or promote a subtask to a top-level task.
+
+### 17. Move Task (`move_task`)
+
+* **MCP Tool:** `move_task`
+* **CLI Command:** `task-master move [options]`
+* **Description:** `Move a task or subtask to a new position within the task hierarchy.`
+* **Key Parameters/Options:**
+ * `from`: `Required. ID of the task/subtask to move (e.g., "5" or "5.2"). Can be comma-separated for multiple tasks.` (CLI: `--from `)
+ * `to`: `Required. ID of the destination (e.g., "7" or "7.3"). Must match the number of source IDs if comma-separated.` (CLI: `--to `)
+ * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Reorganize tasks by moving them within the hierarchy. Supports various scenarios like:
+ * Moving a task to become a subtask
+ * Moving a subtask to become a standalone task
+ * Moving a subtask to a different parent
+ * Reordering subtasks within the same parent
+ * Moving a task to a new, non-existent ID (automatically creates placeholders)
+ * Moving multiple tasks at once with comma-separated IDs
+* **Validation Features:**
+ * Allows moving tasks to non-existent destination IDs (creates placeholder tasks)
+ * Prevents moving to existing task IDs that already have content (to avoid overwriting)
+ * Validates that source tasks exist before attempting to move them
+ * Maintains proper parent-child relationships
+* **Example CLI:** `task-master move --from=5.2 --to=7.3` to move subtask 5.2 to become subtask 7.3.
+* **Example Multi-Move:** `task-master move --from=10,11,12 --to=16,17,18` to move multiple tasks to new positions.
+* **Common Use:** Resolving merge conflicts in tasks.json when multiple team members create tasks on different branches.
+
+---
+
+## Dependency Management
+
+### 18. Add Dependency (`add_dependency`)
+
+* **MCP Tool:** `add_dependency`
+* **CLI Command:** `task-master add-dependency [options]`
+* **Description:** `Define a dependency in Taskmaster, making one task a prerequisite for another.`
+* **Key Parameters/Options:**
+ * `id`: `Required. The ID of the Taskmaster task that will depend on another.` (CLI: `-i, --id `)
+ * `dependsOn`: `Required. The ID of the Taskmaster task that must be completed first, the prerequisite.` (CLI: `-d, --depends-on `)
+ * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Establish the correct order of execution between tasks.
+
+### 19. Remove Dependency (`remove_dependency`)
+
+* **MCP Tool:** `remove_dependency`
+* **CLI Command:** `task-master remove-dependency [options]`
+* **Description:** `Remove a dependency relationship between two Taskmaster tasks.`
+* **Key Parameters/Options:**
+ * `id`: `Required. The ID of the Taskmaster task you want to remove a prerequisite from.` (CLI: `-i, --id `)
+ * `dependsOn`: `Required. The ID of the Taskmaster task that should no longer be a prerequisite.` (CLI: `-d, --depends-on `)
+ * `tag`: `Specify which tag context to operate on. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Update task relationships when the order of execution changes.
+
+### 20. Validate Dependencies (`validate_dependencies`)
+
+* **MCP Tool:** `validate_dependencies`
+* **CLI Command:** `task-master validate-dependencies [options]`
+* **Description:** `Check your Taskmaster tasks for dependency issues (like circular references or links to non-existent tasks) without making changes.`
+* **Key Parameters/Options:**
+ * `tag`: `Specify which tag context to validate. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Audit the integrity of your task dependencies.
+
+### 21. Fix Dependencies (`fix_dependencies`)
+
+* **MCP Tool:** `fix_dependencies`
+* **CLI Command:** `task-master fix-dependencies [options]`
+* **Description:** `Automatically fix dependency issues (like circular references or links to non-existent tasks) in your Taskmaster tasks.`
+* **Key Parameters/Options:**
+ * `tag`: `Specify which tag context to fix dependencies in. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Clean up dependency errors automatically.
+
+---
+
+## Analysis & Reporting
+
+### 22. Analyze Project Complexity (`analyze_project_complexity`)
+
+* **MCP Tool:** `analyze_project_complexity`
+* **CLI Command:** `task-master analyze-complexity [options]`
+* **Description:** `Have Taskmaster analyze your tasks to determine their complexity and suggest which ones need to be broken down further.`
+* **Key Parameters/Options:**
+ * `output`: `Where to save the complexity analysis report. Default is '.taskmaster/reports/task-complexity-report.json' (or '..._tagname.json' if a tag is used).` (CLI: `-o, --output `)
+ * `threshold`: `The minimum complexity score (1-10) that should trigger a recommendation to expand a task.` (CLI: `-t, --threshold `)
+ * `research`: `Enable research role for more accurate complexity analysis. Requires appropriate API key.` (CLI: `-r, --research`)
+ * `tag`: `Specify which tag context to analyze. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Used before breaking down tasks to identify which ones need the most attention.
+* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
+
+### 23. View Complexity Report (`complexity_report`)
+
+* **MCP Tool:** `complexity_report`
+* **CLI Command:** `task-master complexity-report [options]`
+* **Description:** `Display the task complexity analysis report in a readable format.`
+* **Key Parameters/Options:**
+ * `tag`: `Specify which tag context to show the report for. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to the complexity report (default: '.taskmaster/reports/task-complexity-report.json').` (CLI: `-f, --file `)
+* **Usage:** Review and understand the complexity analysis results after running analyze-complexity.
+
+---
+
+## File Management
+
+### 24. Generate Task Files (`generate`)
+
+* **MCP Tool:** `generate`
+* **CLI Command:** `task-master generate [options]`
+* **Description:** `Create or update individual Markdown files for each task based on your tasks.json.`
+* **Key Parameters/Options:**
+ * `output`: `The directory where Taskmaster should save the task files (default: in a 'tasks' directory).` (CLI: `-o, --output `)
+ * `tag`: `Specify which tag context to generate files for. Defaults to the current active tag.` (CLI: `--tag `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+* **Usage:** Run this after making changes to tasks.json to keep individual task files up to date. This command is now manual and no longer runs automatically.
+
+---
+
+## AI-Powered Research
+
+### 25. Research (`research`)
+
+* **MCP Tool:** `research`
+* **CLI Command:** `task-master research [options]`
+* **Description:** `Perform AI-powered research queries with project context to get fresh, up-to-date information beyond the AI's knowledge cutoff.`
+* **Key Parameters/Options:**
+ * `query`: `Required. Research query/prompt (e.g., "What are the latest best practices for React Query v5?").` (CLI: `[query]` positional or `-q, --query `)
+ * `taskIds`: `Comma-separated list of task/subtask IDs from the current tag context (e.g., "15,16.2,17").` (CLI: `-i, --id `)
+ * `filePaths`: `Comma-separated list of file paths for context (e.g., "src/api.js,docs/readme.md").` (CLI: `-f, --files `)
+ * `customContext`: `Additional custom context text to include in the research.` (CLI: `-c, --context `)
+ * `includeProjectTree`: `Include project file tree structure in context (default: false).` (CLI: `--tree`)
+ * `detailLevel`: `Detail level for the research response: 'low', 'medium', 'high' (default: medium).` (CLI: `--detail `)
+ * `saveTo`: `Task or subtask ID (e.g., "15", "15.2") to automatically save the research conversation to.` (CLI: `--save-to `)
+ * `saveFile`: `If true, saves the research conversation to a markdown file in '.taskmaster/docs/research/'.` (CLI: `--save-file`)
+ * `noFollowup`: `Disables the interactive follow-up question menu in the CLI.` (CLI: `--no-followup`)
+ * `tag`: `Specify which tag context to use for task-based context gathering. Defaults to the current active tag.` (CLI: `--tag `)
+ * `projectRoot`: `The directory of the project. Must be an absolute path.` (CLI: Determined automatically)
+* **Usage:** **This is a POWERFUL tool that agents should use FREQUENTLY** to:
+ * Get fresh information beyond knowledge cutoff dates
+ * Research latest best practices, library updates, security patches
+ * Find implementation examples for specific technologies
+ * Validate approaches against current industry standards
+ * Get contextual advice based on project files and tasks
+* **When to Consider Using Research:**
+ * **Before implementing any task** - Research current best practices
+ * **When encountering new technologies** - Get up-to-date implementation guidance (libraries, apis, etc)
+ * **For security-related tasks** - Find latest security recommendations
+ * **When updating dependencies** - Research breaking changes and migration guides
+ * **For performance optimization** - Get current performance best practices
+ * **When debugging complex issues** - Research known solutions and workarounds
+* **Research + Action Pattern:**
+ * Use `research` to gather fresh information
+ * Use `update_subtask` to commit findings with timestamps
+ * Use `update_task` to incorporate research into task details
+ * Use `add_task` with research flag for informed task creation
+* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. The research provides FRESH data beyond the AI's training cutoff, making it invaluable for current best practices and recent developments.
+
+---
+
+## Tag Management
+
+This new suite of commands allows you to manage different task contexts (tags).
+
+### 26. List Tags (`tags`)
+
+* **MCP Tool:** `list_tags`
+* **CLI Command:** `task-master tags [options]`
+* **Description:** `List all available tags with task counts, completion status, and other metadata.`
+* **Key Parameters/Options:**
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+ * `--show-metadata`: `Include detailed metadata in the output (e.g., creation date, description).` (CLI: `--show-metadata`)
+
+### 27. Add Tag (`add_tag`)
+
+* **MCP Tool:** `add_tag`
+* **CLI Command:** `task-master add-tag [options]`
+* **Description:** `Create a new, empty tag context, or copy tasks from another tag.`
+* **Key Parameters/Options:**
+ * `tagName`: `Name of the new tag to create (alphanumeric, hyphens, underscores).` (CLI: `` positional)
+ * `--from-branch`: `Creates a tag with a name derived from the current git branch, ignoring the argument.` (CLI: `--from-branch`)
+ * `--copy-from-current`: `Copy tasks from the currently active tag to the new tag.` (CLI: `--copy-from-current`)
+ * `--copy-from `: `Copy tasks from a specific source tag to the new tag.` (CLI: `--copy-from `)
+ * `--description `: `Provide an optional description for the new tag.` (CLI: `-d, --description `)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+
+### 28. Delete Tag (`delete_tag`)
+
+* **MCP Tool:** `delete_tag`
+* **CLI Command:** `task-master delete-tag [options]`
+* **Description:** `Permanently delete a tag and all of its associated tasks.`
+* **Key Parameters/Options:**
+ * `tagName`: `Name of the tag to delete.` (CLI: `` positional)
+ * `--yes`: `Skip the confirmation prompt.` (CLI: `-y, --yes`)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+
+### 29. Use Tag (`use_tag`)
+
+* **MCP Tool:** `use_tag`
+* **CLI Command:** `task-master use-tag `
+* **Description:** `Switch your active task context to a different tag.`
+* **Key Parameters/Options:**
+ * `tagName`: `Name of the tag to switch to.` (CLI: `` positional)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+
+### 30. Rename Tag (`rename_tag`)
+
+* **MCP Tool:** `rename_tag`
+* **CLI Command:** `task-master rename-tag `
+* **Description:** `Rename an existing tag.`
+* **Key Parameters/Options:**
+ * `oldName`: `The current name of the tag.` (CLI: `` positional)
+ * `newName`: `The new name for the tag.` (CLI: `` positional)
+ * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `)
+
+### 31. Copy Tag (`copy_tag`)
+
+* **MCP Tool:** `copy_tag`
+* **CLI Command:** `task-master copy-tag [options]`
+* **Description:** `Copy an entire tag context, including all its tasks and metadata, to a new tag.`
+* **Key Parameters/Options:**
+ * `sourceName`: `Name of the tag to copy from.` (CLI: `` positional)
+ * `targetName`: `Name of the new tag to create.` (CLI: `` positional)
+ * `--description `: `Optional description for the new tag.` (CLI: `-d, --description `)
+
+---
+
+## Miscellaneous
+
+### 32. Sync Readme (`sync-readme`) -- experimental
+
+* **MCP Tool:** N/A
+* **CLI Command:** `task-master sync-readme [options]`
+* **Description:** `Exports your task list to your project's README.md file, useful for showcasing progress.`
+* **Key Parameters/Options:**
+ * `status`: `Filter tasks by status (e.g., 'pending', 'done').` (CLI: `-s, --status `)
+ * `withSubtasks`: `Include subtasks in the export.` (CLI: `--with-subtasks`)
+ * `tag`: `Specify which tag context to export from. Defaults to the current active tag.` (CLI: `--tag `)
+
+---
+
+## Environment Variables Configuration (Updated)
+
+Taskmaster primarily uses the **`.taskmaster/config.json`** file (in project root) for configuration (models, parameters, logging level, etc.), managed via `task-master models --setup`.
+
+Environment variables are used **only** for sensitive API keys related to AI providers and specific overrides like the Ollama base URL:
+
+* **API Keys (Required for corresponding provider):**
+ * `ANTHROPIC_API_KEY`
+ * `PERPLEXITY_API_KEY`
+ * `OPENAI_API_KEY`
+ * `GOOGLE_API_KEY`
+ * `MISTRAL_API_KEY`
+ * `AZURE_OPENAI_API_KEY` (Requires `AZURE_OPENAI_ENDPOINT` too)
+ * `OPENROUTER_API_KEY`
+ * `XAI_API_KEY`
+ * `OLLAMA_API_KEY` (Requires `OLLAMA_BASE_URL` too)
+* **Endpoints (Optional/Provider Specific inside .taskmaster/config.json):**
+ * `AZURE_OPENAI_ENDPOINT`
+ * `OLLAMA_BASE_URL` (Default: `http://localhost:11434/api`)
+
+**Set API keys** in your **`.env`** file in the project root (for CLI use) or within the `env` section of your **`.cursor/mcp.json`** file (for MCP/Cursor integration). All other settings (model choice, max tokens, temperature, log level, custom endpoints) are managed in `.taskmaster/config.json` via `task-master models` command or `models` MCP tool.
+
+---
+
+For details on how these commands fit into the development process, see the [Development Workflow Guide](mdc:.cursor/rules/dev_workflow.mdc).
diff --git a/packages/.env.example b/packages/.env.example
new file mode 100644
index 0000000..2c5babf
--- /dev/null
+++ b/packages/.env.example
@@ -0,0 +1,10 @@
+# API Keys (Required to enable respective provider)
+ANTHROPIC_API_KEY="your_anthropic_api_key_here" # Required: Format: sk-ant-api03-...
+PERPLEXITY_API_KEY="your_perplexity_api_key_here" # Optional: Format: pplx-...
+OPENAI_API_KEY="your_openai_api_key_here" # Optional, for OpenAI/OpenRouter models. Format: sk-proj-...
+GOOGLE_API_KEY="your_google_api_key_here" # Optional, for Google Gemini models.
+MISTRAL_API_KEY="your_mistral_key_here" # Optional, for Mistral AI models.
+XAI_API_KEY="YOUR_XAI_KEY_HERE" # Optional, for xAI AI models.
+AZURE_OPENAI_API_KEY="your_azure_key_here" # Optional, for Azure OpenAI models (requires endpoint in .taskmaster/config.json).
+OLLAMA_API_KEY="your_ollama_api_key_here" # Optional: For remote Ollama servers that require authentication.
+GITHUB_API_KEY="your_github_api_key_here" # Optional: For GitHub import/export features. Format: ghp_... or github_pat_...
\ No newline at end of file
diff --git a/packages/.gitignore b/packages/.gitignore
new file mode 100644
index 0000000..db6295f
--- /dev/null
+++ b/packages/.gitignore
@@ -0,0 +1,25 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+dev-debug.log
+
+# Dependency directories
+node_modules/
+
+# Environment variables
+.env
+
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# OS specific
+.DS_Store
\ No newline at end of file
diff --git a/packages/.guile.instructions.md b/packages/.guile.instructions.md
new file mode 100644
index 0000000..dd0d706
--- /dev/null
+++ b/packages/.guile.instructions.md
@@ -0,0 +1,846 @@
+# Guile Scheme Coding Instructions for Home Lab Tool
+
+## Functional Programming Principles
+
+**Core Philosophy**: Functional programming is about actions, data, and computation - compose small, pure functions to build complex behaviors.
+
+### 1. Pure Functions First
+- Functions should be deterministic and side-effect free when possible
+- Separate pure computation from I/O operations
+- Use immutable data structures as default
+
+```scheme
+;; Good: Pure function
+(define (calculate-deployment-hash config)
+ (sha256 (scm->json-string config)))
+
+;; Better: Separate pure logic from I/O
+(define (deployment-ready? machine-config current-state)
+ (and (eq? (assoc-ref machine-config 'status) 'configured)
+ (eq? (assoc-ref current-state 'connectivity) 'online)))
+
+;; I/O operations separate
+(define (check-machine-deployment machine)
+ (let ((config (load-machine-config machine))
+ (state (probe-machine-state machine)))
+ (deployment-ready? config state)))
+```
+
+### 2. Data-Driven Design
+- Represent configurations and state as data structures
+- Use association lists (alists) and vectors for structured data
+- Leverage Guile's homoiconicity (code as data)
+
+```scheme
+;; Machine configuration as data
+(define machine-specs
+ `((grey-area
+ (services (ollama jellyfin forgejo))
+ (deployment-method deploy-rs)
+ (backup-schedule weekly))
+ (sleeper-service
+ (services (nfs zfs monitoring))
+ (deployment-method hybrid-update)
+ (backup-schedule daily))))
+
+;; Operations on data
+(define (get-machine-services machine)
+ (assoc-ref (assoc-ref machine-specs machine) 'services))
+
+(define (machines-with-service service)
+ (filter (lambda (machine-spec)
+ (member service (get-machine-services (car machine-spec))))
+ machine-specs))
+```
+
+## Guile-Specific Idioms
+
+### 3. Module Organization
+- Use meaningful module hierarchies
+- Export only necessary public interfaces
+- Group related functionality together
+
+```scheme
+;; File: modules/lab/machines.scm
+(define-module (lab machines)
+ #:use-module (srfi srfi-1) ; List processing
+ #:use-module (srfi srfi-26) ; Cut/cute
+ #:use-module (ice-9 match) ; Pattern matching
+ #:use-module (ssh session)
+ #:export (machine-status
+ deploy-machine
+ list-machines
+ machine-services))
+
+;; File: modules/lab/deployment.scm
+(define-module (lab deployment)
+ #:use-module (lab machines)
+ #:use-module (json)
+ #:export (deploy-rs
+ hybrid-update
+ rollback-deployment))
+```
+
+### 4. Error Handling the Scheme Way
+- Use exceptions for exceptional conditions
+- Return #f or special values for expected failures
+- Provide meaningful error context
+
+```scheme
+;; Use exceptions for programming errors
+(define (deploy-machine machine method)
+ (unless (member machine (list-machines))
+ (throw 'invalid-machine "Unknown machine" machine))
+ (unless (member method '(deploy-rs hybrid-update legacy))
+ (throw 'invalid-method "Unknown deployment method" method))
+ ;; ... deployment logic)
+
+;; Return #f for expected failures
+(define (machine-reachable? machine)
+ (catch #t
+ (lambda ()
+ (ssh-connect machine)
+ #t)
+ (lambda (key . args)
+ #f)))
+
+;; Provide context with failure info
+(define (deployment-result success? machine method details)
+ `((success . ,success?)
+ (machine . ,machine)
+ (method . ,method)
+ (timestamp . ,(current-time))
+ (details . ,details)))
+```
+
+### 5. Higher-Order Functions and Composition
+- Use map, filter, fold for list processing
+- Compose functions to build complex operations
+- Leverage SRFI-1 for advanced list operations
+
+```scheme
+(use-modules (srfi srfi-1))
+
+;; Functional composition
+(define (healthy-machines machines)
+ (filter machine-reachable?
+ (filter (lambda (m) (not (maintenance-mode? m)))
+ machines)))
+
+;; Map operations across machines
+(define (update-all-machines)
+ (map (lambda (machine)
+ (cons machine (update-machine machine)))
+ (healthy-machines (list-machines))))
+
+;; Fold for aggregation
+(define (deployment-summary results)
+ (fold (lambda (result acc)
+ (if (assoc-ref result 'success)
+ (cons 'successful (1+ (assoc-ref acc 'successful)))
+ (cons 'failed (1+ (assoc-ref acc 'failed)))))
+ '((successful . 0) (failed . 0))
+ results))
+```
+
+### 6. Pattern Matching for Control Flow
+- Use `match` for destructuring and dispatch
+- Pattern match on data structures
+- Cleaner than nested if/cond statements
+
+```scheme
+(use-modules (ice-9 match))
+
+(define (handle-deployment-event event)
+ (match event
+ (('start machine method)
+ (log-info "Starting deployment of ~a using ~a" machine method))
+
+ (('progress machine percent)
+ (update-progress-bar machine percent))
+
+ (('success machine result)
+ (log-success "Deployment completed: ~a" machine)
+ (notify-success machine result))
+
+ (('error machine error-msg)
+ (log-error "Deployment failed: ~a - ~a" machine error-msg)
+ (initiate-rollback machine))
+
+ (_ (log-warning "Unknown event: ~a" event))))
+
+;; Pattern matching for configuration parsing
+(define (parse-machine-config config-sexp)
+ (match config-sexp
+ (('machine name ('services services ...) ('options options ...))
+ `((name . ,name)
+ (services . ,services)
+ (options . ,(alist->hash-table options))))
+
+ (_ (throw 'invalid-config "Malformed machine config" config-sexp))))
+```
+
+### 7. REPL-Driven Development
+- Design for interactive development
+- Provide introspection functions
+- Make state queryable and modifiable
+
+```scheme
+;; REPL helpers for development
+(define (debug-machine-state machine)
+ "Display comprehensive machine state for debugging"
+ (format #t "Machine: ~a~%" machine)
+ (format #t "Status: ~a~%" (machine-status machine))
+ (format #t "Services: ~a~%" (machine-services machine))
+ (format #t "Last deployment: ~a~%" (last-deployment machine))
+ (format #t "Reachable: ~a~%" (machine-reachable? machine)))
+
+;; Interactive deployment with confirmation
+(define (interactive-deploy machine)
+ (let ((current-config (get-machine-config machine)))
+ (display-config current-config)
+ (when (yes-or-no? "Proceed with deployment?")
+ (deploy-machine machine 'deploy-rs))))
+
+;; State introspection
+(define (lab-status)
+ `((total-machines . ,(length (list-machines)))
+ (reachable . ,(length (filter machine-reachable? (list-machines))))
+ (services-running . ,(total-running-services))
+ (pending-deployments . ,(length (pending-deployments)))))
+```
+
+### 8. Concurrency with Fibers
+- Use fibers for concurrent operations
+- Non-blocking I/O for better performance
+- Coordinate parallel deployments safely
+
+```scheme
+(use-modules (fibers) (fibers channels))
+
+;; Concurrent machine checking
+(define (check-all-machines-concurrent machines)
+ (run-fibers
+ (lambda ()
+ (let ((results-channel (make-channel)))
+ ;; Spawn fiber for each machine
+ (for-each (lambda (machine)
+ (spawn-fiber
+ (lambda ()
+ (let ((status (check-machine-status machine)))
+ (put-message results-channel
+ (cons machine status))))))
+ machines)
+
+ ;; Collect results
+ (let loop ((remaining (length machines))
+ (results '()))
+ (if (zero? remaining)
+ results
+ (loop (1- remaining)
+ (cons (get-message results-channel) results))))))))
+
+;; Parallel deployment with coordination
+(define (deploy-machines-parallel machines)
+ (run-fibers
+ (lambda ()
+ (let ((deployment-channel (make-channel))
+ (coordinator (spawn-fiber (deployment-coordinator deployment-channel))))
+ (par-map (lambda (machine)
+ (deploy-with-coordination machine deployment-channel))
+ machines)))))
+```
+
+### 9. MCP Server Implementation Patterns
+- Structured message handling
+- Capability-based tool organization
+- Resource management with caching
+
+```scheme
+;; MCP message dispatch
+(define (handle-mcp-request request)
+ (match (json-ref request "method")
+ ("tools/list"
+ (mcp-tools-list))
+
+ ("tools/call"
+ (let ((tool (json-ref request "params" "name"))
+ (args (json-ref request "params" "arguments")))
+ (call-lab-tool tool args)))
+
+ ("resources/list"
+ (mcp-resources-list))
+
+ ("resources/read"
+ (let ((uri (json-ref request "params" "uri")))
+ (read-lab-resource uri)))
+
+ (method
+ (mcp-error -32601 "Method not found" method))))
+
+;; Tool capability definition
+(define lab-tools
+ `((deploy-machine
+ (description . "Deploy configuration to a specific machine")
+ (inputSchema . ,(json-schema
+ `((type . "object")
+ (properties . ((machine (type . "string"))
+ (method (type . "string")
+ (enum . ("deploy-rs" "hybrid-update")))))
+ (required . ("machine")))))
+ (handler . ,deploy-machine-tool))
+
+ (check-status
+ (description . "Check machine status and connectivity")
+ (inputSchema . ,(json-schema
+ `((type . "object")
+ (properties . ((machines (type . "array")
+ (items (type . "string"))))))))
+ (handler . ,check-status-tool))))
+```
+
+### 10. Configuration and Environment
+- Use parameters for configuration
+- Environment-aware defaults
+- Validate configuration on startup
+
+```scheme
+;; Configuration parameters
+(define lab-config-dir
+ (make-parameter (or (getenv "LAB_CONFIG_DIR")
+ "/etc/lab-tool")))
+
+(define deployment-timeout
+ (make-parameter (string->number (or (getenv "DEPLOYMENT_TIMEOUT") "300"))))
+
+(define ssh-key-path
+ (make-parameter (or (getenv "LAB_SSH_KEY")
+ (string-append (getenv "HOME") "/.ssh/lab_key"))))
+
+;; Configuration validation
+(define (validate-lab-config)
+ (unless (file-exists? (lab-config-dir))
+ (throw 'config-error "Lab config directory not found" (lab-config-dir)))
+
+ (unless (file-exists? (ssh-key-path))
+ (throw 'config-error "SSH key not found" (ssh-key-path)))
+
+ (unless (> (deployment-timeout) 0)
+ (throw 'config-error "Invalid deployment timeout" (deployment-timeout))))
+
+;; Initialize with validation
+(define (init-lab-tool)
+ (validate-lab-config)
+ (load-machine-configurations)
+ (initialize-ssh-agent)
+ (setup-logging))
+```
+
+## Code Style Guidelines
+
+### 11. Naming Conventions
+- Use kebab-case for variables and functions
+- Predicates end with `?`
+- Mutating procedures end with `!`
+- Constants in ALL-CAPS with hyphens
+
+```scheme
+;; Good naming
+(define DEFAULT-SSH-PORT 22)
+(define machine-deployment-status ...)
+(define (machine-reachable? machine) ...)
+(define (update-machine-config! machine config) ...)
+
+;; Avoid
+(define defaultSSHPort 22) ; camelCase
+(define machine_status ...) ; snake_case
+(define (is-machine-reachable ...) ; unnecessary 'is-'
+```
+
+### 12. Documentation and Comments
+- Document module purposes and exports
+- Use docstrings for complex functions
+- Comment the "why", not the "what"
+
+```scheme
+(define (deploy-machine machine method)
+ "Deploy configuration to MACHINE using METHOD.
+
+ Returns a deployment result alist with success status, timing,
+ and any error messages. May throw exceptions for invalid inputs."
+
+ ;; Validate inputs early to fail fast
+ (validate-machine machine)
+ (validate-deployment-method method)
+
+ ;; Use atomic operations to prevent partial deployments
+ (call-with-deployment-lock machine
+ (lambda ()
+ (let ((start-time (current-time)))
+ ;; ... deployment logic
+ ))))
+```
+
+### 13. Testing Approach
+- Write tests for pure functions first
+- Mock I/O operations
+- Use SRFI-64 testing framework
+
+```scheme
+(use-modules (srfi srfi-64))
+
+(test-begin "machine-configuration")
+
+(test-equal "machine services extraction"
+ '(ollama jellyfin forgejo)
+ (get-machine-services 'grey-area))
+
+(test-assert "deployment readiness check"
+ (deployment-ready?
+ '((status . configured) (health . good))
+ '((connectivity . online) (load . normal))))
+
+(test-error "invalid machine throws exception"
+ 'invalid-machine
+ (deploy-machine 'non-existent-machine 'deploy-rs))
+
+(test-end "machine-configuration")
+```
+
+## Project Structure Best Practices
+
+### 14. Module Organization
+```
+modules/
+├── lab/
+│ ├── core.scm ; Core data structures and utilities
+│ ├── machines.scm ; Machine management
+│ ├── deployment.scm ; Deployment strategies
+│ ├── monitoring.scm ; Status checking and metrics
+│ └── config.scm ; Configuration handling
+├── mcp/
+│ ├── server.scm ; MCP server implementation
+│ ├── tools.scm ; MCP tool definitions
+│ └── resources.scm ; MCP resource handlers
+└── utils/
+ ├── ssh.scm ; SSH utilities
+ ├── json.scm ; JSON helpers
+ └── logging.scm ; Logging facilities
+```
+
+### 15. Build and Development Workflow
+- Use Guile's module compilation
+- Leverage REPL for iterative development
+- Provide development/production configurations
+
+```scheme
+;; Development helpers in separate module
+(define-module (lab dev)
+ #:use-module (lab core)
+ #:export (reload-config
+ reset-state
+ dev-deploy))
+
+;; Hot-reload for development
+(define (reload-config)
+ (reload-module (resolve-module '(lab config)))
+ (init-lab-tool))
+
+;; Safe deployment for development
+(define (dev-deploy machine)
+ (if (eq? (current-environment) 'development)
+ (deploy-machine machine 'deploy-rs)
+ (error "dev-deploy only available in development mode")))
+```
+
+## VS Code and GitHub Copilot Integration
+
+### 16. MCP Client Integration with VS Code
+- Implement MCP client in VS Code extension
+- Bridge home lab context to Copilot
+- Provide real-time infrastructure state
+
+```typescript
+// VS Code extension structure for MCP integration
+// File: vscode-extension/src/extension.ts
+import * as vscode from 'vscode';
+import { MCPClient } from './mcp-client';
+
+export function activate(context: vscode.ExtensionContext) {
+ const mcpClient = new MCPClient('stdio', {
+ command: 'guile',
+ args: ['-c', '(use-modules (mcp server)) (run-mcp-server)']
+ });
+
+ // Register commands for home lab operations
+ const deployCommand = vscode.commands.registerCommand(
+ 'homelab.deploy',
+ async (machine: string) => {
+ const result = await mcpClient.callTool('deploy-machine', {
+ machine: machine,
+ method: 'deploy-rs'
+ });
+ vscode.window.showInformationMessage(
+ `Deployment ${result.success ? 'succeeded' : 'failed'}`
+ );
+ }
+ );
+
+ // Provide context to Copilot through workspace state
+ const statusProvider = new HomeLab StatusProvider(mcpClient);
+ context.subscriptions.push(
+ vscode.workspace.registerTextDocumentContentProvider(
+ 'homelab', statusProvider
+ )
+ );
+
+ context.subscriptions.push(deployCommand);
+}
+
+class HomeLabStatusProvider implements vscode.TextDocumentContentProvider {
+ constructor(private mcpClient: MCPClient) {}
+
+ async provideTextDocumentContent(uri: vscode.Uri): Promise {
+ // Fetch current lab state for Copilot context
+ const resources = await this.mcpClient.listResources();
+ const status = await this.mcpClient.readResource('machines://status/all');
+
+ return `# Home Lab Status
+Current Infrastructure State:
+${JSON.stringify(status, null, 2)}
+
+Available Resources:
+${resources.map(r => `- ${r.uri}: ${r.description}`).join('\n')}
+`;
+ }
+}
+```
+
+### 17. MCP Server Configuration for IDE Integration
+- Provide IDE-specific tools and resources
+- Format responses for developer consumption
+- Include code suggestions and snippets
+
+```scheme
+;; IDE-specific MCP tools
+(define ide-tools
+ `((generate-nix-config
+ (description . "Generate NixOS configuration for new machine")
+ (inputSchema . ,(json-schema
+ `((type . "object")
+ (properties . ((machine-name (type . "string"))
+ (services (type . "array")
+ (items (type . "string")))
+ (hardware-profile (type . "string"))))
+ (required . ("machine-name")))))
+ (handler . ,generate-nix-config-tool))
+
+ (suggest-deployment-strategy
+ (description . "Suggest optimal deployment strategy for changes")
+ (inputSchema . ,(json-schema
+ `((type . "object")
+ (properties . ((changed-files (type . "array")
+ (items (type . "string")))
+ (target-machines (type . "array")
+ (items (type . "string")))))
+ (required . ("changed-files")))))
+ (handler . ,suggest-deployment-strategy-tool))
+
+ (validate-config
+ (description . "Validate NixOS configuration syntax and dependencies")
+ (inputSchema . ,(json-schema
+ `((type . "object")
+ (properties . ((config-path (type . "string"))
+ (machine (type . "string"))))
+ (required . ("config-path")))))
+ (handler . ,validate-config-tool))))
+
+;; IDE-specific resources
+(define ide-resources
+ `(("homelab://templates/machine-config"
+ (description . "Template for new machine configuration")
+ (mimeType . "application/x-nix"))
+
+ ("homelab://examples/service-configs"
+ (description . "Example service configurations")
+ (mimeType . "application/x-nix"))
+
+ ("homelab://docs/deployment-guide"
+ (description . "Step-by-step deployment procedures")
+ (mimeType . "text/markdown"))
+
+ ("homelab://status/real-time"
+ (description . "Real-time infrastructure status for context")
+ (mimeType . "application/json"))))
+
+;; Generate contextual code suggestions
+(define (generate-nix-config-tool args)
+ (let ((machine-name (assoc-ref args "machine-name"))
+ (services (assoc-ref args "services"))
+ (hardware-profile (assoc-ref args "hardware-profile")))
+
+ `((content . ,(format #f "# Generated configuration for ~a
+{ config, pkgs, ... }:
+
+{
+ imports = [
+ ./hardware-configuration.nix
+ ~/args
+ ];
+
+ # Machine-specific configuration
+ networking.hostName = \"~a\";
+
+ # Services configuration
+~a
+
+ # System packages
+ environment.systemPackages = with pkgs; [
+ # Add your packages here
+ ];
+
+ system.stateVersion = \"24.05\";
+}"
+ machine-name
+ machine-name
+ (if services
+ (string-join
+ (map (lambda (service)
+ (format #f " services.~a.enable = true;" service))
+ services)
+ "\n")
+ " # No services specified")))
+ (isError . #f))))
+```
+
+### 18. Copilot Context Enhancement
+- Provide infrastructure context to improve suggestions
+- Include deployment patterns and best practices
+- Real-time system state for informed recommendations
+
+```scheme
+;; Context provider for Copilot integration
+(define (provide-copilot-context)
+ `((infrastructure-state . ,(get-current-infrastructure-state))
+ (deployment-patterns . ,(get-common-deployment-patterns))
+ (service-configurations . ,(get-service-config-templates))
+ (best-practices . ,(get-deployment-best-practices))
+ (current-issues . ,(get-active-alerts))))
+
+(define (get-current-infrastructure-state)
+ `((machines . ,(map (lambda (machine)
+ `((name . ,machine)
+ (status . ,(machine-status machine))
+ (services . ,(machine-services machine))
+ (last-deployment . ,(last-deployment-time machine))))
+ (list-machines)))
+ (network-topology . ,(get-network-topology))
+ (resource-usage . ,(get-resource-utilization))))
+
+(define (get-common-deployment-patterns)
+ `((safe-deployment . "Use deploy-rs for production, hybrid-update for development")
+ (rollback-strategy . "Always test deployments in staging first")
+ (service-dependencies . "Ensure database services start before applications")
+ (backup-before-deploy . "Create snapshots before major configuration changes")))
+
+;; Format context for IDE consumption
+(define (format-ide-context context)
+ (scm->json-string context #:pretty #t))
+```
+
+### 19. VS Code Extension Development
+- Create extension for seamless MCP integration
+- Provide commands, views, and context
+- Enable real-time collaboration with infrastructure
+
+```typescript
+// package.json for VS Code extension
+{
+ "name": "homelab-mcp-integration",
+ "displayName": "Home Lab MCP Integration",
+ "description": "Integrate home lab infrastructure with VS Code through MCP",
+ "version": "0.1.0",
+ "engines": {
+ "vscode": "^1.74.0"
+ },
+ "categories": ["Other"],
+ "activationEvents": [
+ "onCommand:homelab.connect",
+ "workspaceContains:**/flake.nix"
+ ],
+ "main": "./out/extension.js",
+ "contributes": {
+ "commands": [
+ {
+ "command": "homelab.deploy",
+ "title": "Deploy Machine",
+ "category": "Home Lab"
+ },
+ {
+ "command": "homelab.status",
+ "title": "Check Status",
+ "category": "Home Lab"
+ },
+ {
+ "command": "homelab.generateConfig",
+ "title": "Generate Config",
+ "category": "Home Lab"
+ }
+ ],
+ "views": {
+ "explorer": [
+ {
+ "id": "homelabStatus",
+ "name": "Home Lab Status",
+ "when": "homelab:connected"
+ }
+ ]
+ },
+ "viewsContainers": {
+ "activitybar": [
+ {
+ "id": "homelab",
+ "title": "Home Lab",
+ "icon": "$(server-environment)"
+ }
+ ]
+ }
+ }
+}
+
+// MCP Client implementation
+class MCPClient {
+ private transport: MCPTransport;
+ private capabilities: MCPCapabilities;
+
+ constructor(transportType: 'stdio' | 'websocket', config: any) {
+ this.transport = this.createTransport(transportType, config);
+ this.initialize();
+ }
+
+ async callTool(name: string, arguments: any): Promise {
+ return this.transport.request('tools/call', {
+ name: name,
+ arguments: arguments
+ });
+ }
+
+ async listResources(): Promise {
+ const response = await this.transport.request('resources/list', {});
+ return response.resources;
+ }
+
+ async readResource(uri: string): Promise {
+ return this.transport.request('resources/read', { uri });
+ }
+
+ // Integration with Copilot context
+ async getCopilotContext(): Promise {
+ const context = await this.readResource('homelab://context/copilot');
+ return context.content;
+ }
+}
+```
+
+### 20. GitHub Copilot Workspace Integration
+- Configure workspace for optimal Copilot suggestions
+- Provide infrastructure context files
+- Set up context patterns for deployment scenarios
+
+```json
+// .vscode/settings.json
+{
+ "github.copilot.enable": {
+ "*": true,
+ "yaml": true,
+ "nix": true,
+ "scheme": true
+ },
+ "github.copilot.advanced": {
+ "length": 500,
+ "temperature": 0.2
+ },
+ "homelab.mcpServer": {
+ "command": "guile",
+ "args": ["-L", "modules", "-c", "(use-modules (mcp server)) (run-mcp-server)"],
+ "autoStart": true
+ },
+ "files.associations": {
+ "*.scm": "scheme",
+ "flake.lock": "json"
+ }
+}
+
+// .copilot/context.md for workspace context
+```markdown
+# Home Lab Infrastructure Context
+
+## Current Architecture
+- NixOS-based infrastructure with multiple machines
+- Deploy-rs for safe deployments
+- Services: Ollama, Jellyfin, Forgejo, NFS, ZFS
+- Network topology: reverse-proxy, grey-area, sleeper-service, congenital-optimist
+
+## Common Patterns
+- Use `deploy-rs` for production deployments
+- Test with `hybrid-update` in development
+- Always backup before major changes
+- Follow NixOS module structure in `/modules/`
+
+## Configuration Standards
+- Machine configs in `/machines/{hostname}/`
+- Shared modules in `/modules/`
+- Service-specific configs in `services/` subdirectories
+```
+
+### 21. Real-time Context Updates
+- Stream infrastructure changes to VS Code
+- Update Copilot context automatically
+- Provide deployment feedback in editor
+
+```scheme
+;; Real-time context streaming
+(define (start-context-stream port)
+ "Stream infrastructure changes to connected IDE clients"
+ (let ((clients (make-hash-table)))
+ (spawn-fiber
+ (lambda ()
+ (let loop ()
+ (let ((update (get-infrastructure-update)))
+ (hash-for-each
+ (lambda (client-id websocket)
+ (catch #t
+ (lambda ()
+ (websocket-send websocket
+ (scm->json-string update)))
+ (lambda (key . args)
+ (hash-remove! clients client-id))))
+ clients)
+ (sleep 5)
+ (loop)))))
+
+ ;; WebSocket server for IDE connections
+ (run-websocket-server
+ (lambda (ws)
+ (let ((client-id (generate-client-id)))
+ (hash-set! clients client-id ws)
+ (websocket-send ws
+ (scm->json-string
+ `((type . "welcome")
+ (context . ,(get-current-context)))))
+ (handle-client-messages ws client-id clients)))
+ #:port port)))
+
+;; Integration with file watchers
+(define (watch-config-changes)
+ "Watch for configuration file changes and update context"
+ (file-system-watcher
+ (list "/home/geir/Home-lab/machines"
+ "/home/geir/Home-lab/modules")
+ (lambda (event)
+ (match event
+ (('modify path)
+ (when (string-suffix? ".nix" path)
+ (update-copilot-context path)))
+ (_ #f)))))
+```
\ No newline at end of file
diff --git a/packages/.roo/rules-architect/architect-rules b/packages/.roo/rules-architect/architect-rules
new file mode 100644
index 0000000..c1a1ca1
--- /dev/null
+++ b/packages/.roo/rules-architect/architect-rules
@@ -0,0 +1,93 @@
+**Core Directives & Agentivity:**
+# 1. Adhere strictly to the rules defined below.
+# 2. Use tools sequentially, one per message. Adhere strictly to the rules defined below.
+# 3. CRITICAL: ALWAYS wait for user confirmation of success after EACH tool use before proceeding. Do not assume success.
+# 4. Operate iteratively: Analyze task -> Plan steps -> Execute steps one by one.
+# 5. Use tags for *internal* analysis before tool use (context, tool choice, required params).
+# 6. **DO NOT DISPLAY XML TOOL TAGS IN THE OUTPUT.**
+# 7. **DO NOT DISPLAY YOUR THINKING IN THE OUTPUT.**
+
+**Architectural Design & Planning Role (Delegated Tasks):**
+
+Your primary role when activated via `new_task` by the Boomerang orchestrator is to perform specific architectural, design, or planning tasks, focusing on the instructions provided in the delegation message and referencing the relevant `taskmaster-ai` task ID.
+
+1. **Analyze Delegated Task:** Carefully examine the `message` provided by Boomerang. This message contains the specific task scope, context (including the `taskmaster-ai` task ID), and constraints.
+2. **Information Gathering (As Needed):** Use analysis tools to fulfill the task:
+ * `list_files`: Understand project structure.
+ * `read_file`: Examine specific code, configuration, or documentation files relevant to the architectural task.
+ * `list_code_definition_names`: Analyze code structure and relationships.
+ * `use_mcp_tool` (taskmaster-ai): Use `get_task` or `analyze_project_complexity` *only if explicitly instructed* by Boomerang in the delegation message to gather further context beyond what was provided.
+3. **Task Execution (Design & Planning):** Focus *exclusively* on the delegated architectural task, which may involve:
+ * Designing system architecture, component interactions, or data models.
+ * Planning implementation steps or identifying necessary subtasks (to be reported back).
+ * Analyzing technical feasibility, complexity, or potential risks.
+ * Defining interfaces, APIs, or data contracts.
+ * Reviewing existing code/architecture against requirements or best practices.
+4. **Reporting Completion:** Signal completion using `attempt_completion`. Provide a concise yet thorough summary of the outcome in the `result` parameter. This summary is **crucial** for Boomerang to update `taskmaster-ai`. Include:
+ * Summary of design decisions, plans created, analysis performed, or subtasks identified.
+ * Any relevant artifacts produced (e.g., diagrams described, markdown files written - if applicable and instructed).
+ * Completion status (success, failure, needs review).
+ * Any significant findings, potential issues, or context gathered relevant to the next steps.
+5. **Handling Issues:**
+ * **Complexity/Review:** If you encounter significant complexity, uncertainty, or issues requiring further review (e.g., needing testing input, deeper debugging analysis), set the status to 'review' within your `attempt_completion` result and clearly state the reason. **Do not delegate directly.** Report back to Boomerang.
+ * **Failure:** If the task fails (e.g., requirements are contradictory, necessary information unavailable), clearly report the failure and the reason in the `attempt_completion` result.
+6. **Taskmaster Interaction:**
+ * **Primary Responsibility:** Boomerang is primarily responsible for updating Taskmaster (`set_task_status`, `update_task`, `update_subtask`) after receiving your `attempt_completion` result.
+ * **Direct Updates (Rare):** Only update Taskmaster directly if operating autonomously (not under Boomerang's delegation) or if *explicitly* instructed by Boomerang within the `new_task` message.
+7. **Autonomous Operation (Exceptional):** If operating outside of Boomerang's delegation (e.g., direct user request), ensure Taskmaster is initialized before attempting Taskmaster operations (see Taskmaster-AI Strategy below).
+
+**Context Reporting Strategy:**
+
+context_reporting: |
+
+ Strategy:
+ - Focus on providing comprehensive information within the `attempt_completion` `result` parameter.
+ - Boomerang will use this information to update Taskmaster's `description`, `details`, or log via `update_task`/`update_subtask`.
+ - My role is to *report* accurately, not *log* directly to Taskmaster unless explicitly instructed or operating autonomously.
+
+ - **Goal:** Ensure the `result` parameter in `attempt_completion` contains all necessary information for Boomerang to understand the outcome and update Taskmaster effectively.
+ - **Content:** Include summaries of architectural decisions, plans, analysis, identified subtasks, errors encountered, or new context discovered. Structure the `result` clearly.
+ - **Trigger:** Always provide a detailed `result` upon using `attempt_completion`.
+ - **Mechanism:** Boomerang receives the `result` and performs the necessary Taskmaster updates.
+
+**Taskmaster-AI Strategy (for Autonomous Operation):**
+
+# Only relevant if operating autonomously (not delegated by Boomerang).
+taskmaster_strategy:
+ status_prefix: "Begin autonomous responses with either '[TASKMASTER: ON]' or '[TASKMASTER: OFF]'."
+ initialization: |
+
+ - **CHECK FOR TASKMASTER (Autonomous Only):**
+ - Plan: If I need to use Taskmaster tools autonomously, first use `list_files` to check if `tasks/tasks.json` exists.
+ - If `tasks/tasks.json` is present = set TASKMASTER: ON, else TASKMASTER: OFF.
+
+ *Execute the plan described above only if autonomous Taskmaster interaction is required.*
+ if_uninitialized: |
+ 1. **Inform:** "Task Master is not initialized. Autonomous Taskmaster operations cannot proceed."
+ 2. **Suggest:** "Consider switching to Boomerang mode to initialize and manage the project workflow."
+ if_ready: |
+ 1. **Verify & Load:** Optionally fetch tasks using `taskmaster-ai`'s `get_tasks` tool if needed for autonomous context.
+ 2. **Set Status:** Set status to '[TASKMASTER: ON]'.
+ 3. **Proceed:** Proceed with autonomous Taskmaster operations.
+
+**Mode Collaboration & Triggers (Architect Perspective):**
+
+mode_collaboration: |
+ # Architect Mode Collaboration (Focus on receiving from Boomerang and reporting back)
+ - Delegated Task Reception (FROM Boomerang via `new_task`):
+ * Receive specific architectural/planning task instructions referencing a `taskmaster-ai` ID.
+ * Analyze requirements, scope, and constraints provided by Boomerang.
+ - Completion Reporting (TO Boomerang via `attempt_completion`):
+ * Report design decisions, plans, analysis results, or identified subtasks in the `result`.
+ * Include completion status (success, failure, review) and context for Boomerang.
+ * Signal completion of the *specific delegated architectural task*.
+
+mode_triggers:
+ # Conditions that might trigger a switch TO Architect mode (typically orchestrated BY Boomerang based on needs identified by other modes or the user)
+ architect:
+ - condition: needs_architectural_design # e.g., New feature requires system design
+ - condition: needs_refactoring_plan # e.g., Code mode identifies complex refactoring needed
+ - condition: needs_complexity_analysis # e.g., Before breaking down a large feature
+ - condition: design_clarification_needed # e.g., Implementation details unclear
+ - condition: pattern_violation_found # e.g., Code deviates significantly from established patterns
+ - condition: review_architectural_decision # e.g., Boomerang requests review based on 'review' status from another mode
\ No newline at end of file
diff --git a/packages/.roo/rules-ask/ask-rules b/packages/.roo/rules-ask/ask-rules
new file mode 100644
index 0000000..ccacc20
--- /dev/null
+++ b/packages/.roo/rules-ask/ask-rules
@@ -0,0 +1,89 @@
+**Core Directives & Agentivity:**
+# 1. Adhere strictly to the rules defined below.
+# 2. Use tools sequentially, one per message. Adhere strictly to the rules defined below.
+# 3. CRITICAL: ALWAYS wait for user confirmation of success after EACH tool use before proceeding. Do not assume success.
+# 4. Operate iteratively: Analyze task -> Plan steps -> Execute steps one by one.
+# 5. Use tags for *internal* analysis before tool use (context, tool choice, required params).
+# 6. **DO NOT DISPLAY XML TOOL TAGS IN THE OUTPUT.**
+# 7. **DO NOT DISPLAY YOUR THINKING IN THE OUTPUT.**
+
+**Information Retrieval & Explanation Role (Delegated Tasks):**
+
+Your primary role when activated via `new_task` by the Boomerang (orchestrator) mode is to act as a specialized technical assistant. Focus *exclusively* on fulfilling the specific instructions provided in the `new_task` message, referencing the relevant `taskmaster-ai` task ID.
+
+1. **Understand the Request:** Carefully analyze the `message` provided in the `new_task` delegation. This message will contain the specific question, information request, or analysis needed, referencing the `taskmaster-ai` task ID for context.
+2. **Information Gathering:** Utilize appropriate tools to gather the necessary information based *only* on the delegation instructions:
+ * `read_file`: To examine specific file contents.
+ * `search_files`: To find patterns or specific text across the project.
+ * `list_code_definition_names`: To understand code structure in relevant directories.
+ * `use_mcp_tool` (with `taskmaster-ai`): *Only if explicitly instructed* by the Boomerang delegation message to retrieve specific task details (e.g., using `get_task`).
+3. **Formulate Response:** Synthesize the gathered information into a clear, concise, and accurate answer or explanation addressing the specific request from the delegation message.
+4. **Reporting Completion:** Signal completion using `attempt_completion`. Provide a concise yet thorough summary of the outcome in the `result` parameter. This summary is **crucial** for Boomerang to process and potentially update `taskmaster-ai`. Include:
+ * The complete answer, explanation, or analysis formulated in the previous step.
+ * Completion status (success, failure - e.g., if information could not be found).
+ * Any significant findings or context gathered relevant to the question.
+ * Cited sources (e.g., file paths, specific task IDs if used) where appropriate.
+5. **Strict Scope:** Execute *only* the delegated information-gathering/explanation task. Do not perform code changes, execute unrelated commands, switch modes, or attempt to manage the overall workflow. Your responsibility ends with reporting the answer via `attempt_completion`.
+
+**Context Reporting Strategy:**
+
+context_reporting: |
+
+ Strategy:
+ - Focus on providing comprehensive information (the answer/analysis) within the `attempt_completion` `result` parameter.
+ - Boomerang will use this information to potentially update Taskmaster's `description`, `details`, or log via `update_task`/`update_subtask`.
+ - My role is to *report* accurately, not *log* directly to Taskmaster.
+
+ - **Goal:** Ensure the `result` parameter in `attempt_completion` contains the complete and accurate answer/analysis requested by Boomerang.
+ - **Content:** Include the full answer, explanation, or analysis results. Cite sources if applicable. Structure the `result` clearly.
+ - **Trigger:** Always provide a detailed `result` upon using `attempt_completion`.
+ - **Mechanism:** Boomerang receives the `result` and performs any necessary Taskmaster updates or decides the next workflow step.
+
+**Taskmaster Interaction:**
+
+* **Primary Responsibility:** Boomerang is primarily responsible for updating Taskmaster (`set_task_status`, `update_task`, `update_subtask`) after receiving your `attempt_completion` result.
+* **Direct Use (Rare & Specific):** Only use Taskmaster tools (`use_mcp_tool` with `taskmaster-ai`) if *explicitly instructed* by Boomerang within the `new_task` message, and *only* for retrieving information (e.g., `get_task`). Do not update Taskmaster status or content directly.
+
+**Taskmaster-AI Strategy (for Autonomous Operation):**
+
+# Only relevant if operating autonomously (not delegated by Boomerang), which is highly exceptional for Ask mode.
+taskmaster_strategy:
+ status_prefix: "Begin autonomous responses with either '[TASKMASTER: ON]' or '[TASKMASTER: OFF]'."
+ initialization: |
+
+ - **CHECK FOR TASKMASTER (Autonomous Only):**
+ - Plan: If I need to use Taskmaster tools autonomously (extremely rare), first use `list_files` to check if `tasks/tasks.json` exists.
+ - If `tasks/tasks.json` is present = set TASKMASTER: ON, else TASKMASTER: OFF.
+
+ *Execute the plan described above only if autonomous Taskmaster interaction is required.*
+ if_uninitialized: |
+ 1. **Inform:** "Task Master is not initialized. Autonomous Taskmaster operations cannot proceed."
+ 2. **Suggest:** "Consider switching to Boomerang mode to initialize and manage the project workflow."
+ if_ready: |
+ 1. **Verify & Load:** Optionally fetch tasks using `taskmaster-ai`'s `get_tasks` tool if needed for autonomous context (again, very rare for Ask).
+ 2. **Set Status:** Set status to '[TASKMASTER: ON]'.
+ 3. **Proceed:** Proceed with autonomous operations (likely just answering a direct question without workflow context).
+
+**Mode Collaboration & Triggers:**
+
+mode_collaboration: |
+ # Ask Mode Collaboration: Focuses on receiving tasks from Boomerang and reporting back findings.
+ - Delegated Task Reception (FROM Boomerang via `new_task`):
+ * Understand question/analysis request from Boomerang (referencing taskmaster-ai task ID).
+ * Research information or analyze provided context using appropriate tools (`read_file`, `search_files`, etc.) as instructed.
+ * Formulate answers/explanations strictly within the subtask scope.
+ * Use `taskmaster-ai` tools *only* if explicitly instructed in the delegation message for information retrieval.
+ - Completion Reporting (TO Boomerang via `attempt_completion`):
+ * Provide the complete answer, explanation, or analysis results in the `result` parameter.
+ * Report completion status (success/failure) of the information-gathering subtask.
+ * Cite sources or relevant context found.
+
+mode_triggers:
+ # Ask mode does not typically trigger switches TO other modes.
+ # It receives tasks via `new_task` and reports completion via `attempt_completion`.
+ # Triggers defining when OTHER modes might switch TO Ask remain relevant for the overall system,
+ # but Ask mode itself does not initiate these switches.
+ ask:
+ - condition: documentation_needed
+ - condition: implementation_explanation
+ - condition: pattern_documentation
\ No newline at end of file
diff --git a/packages/.roo/rules-boomerang/boomerang-rules b/packages/.roo/rules-boomerang/boomerang-rules
new file mode 100644
index 0000000..636a090
--- /dev/null
+++ b/packages/.roo/rules-boomerang/boomerang-rules
@@ -0,0 +1,181 @@
+**Core Directives & Agentivity:**
+# 1. Adhere strictly to the rules defined below.
+# 2. Use tools sequentially, one per message. Adhere strictly to the rules defined below.
+# 3. CRITICAL: ALWAYS wait for user confirmation of success after EACH tool use before proceeding. Do not assume success.
+# 4. Operate iteratively: Analyze task -> Plan steps -> Execute steps one by one.
+# 5. Use tags for *internal* analysis before tool use (context, tool choice, required params).
+# 6. **DO NOT DISPLAY XML TOOL TAGS IN THE OUTPUT.**
+# 7. **DO NOT DISPLAY YOUR THINKING IN THE OUTPUT.**
+
+**Workflow Orchestration Role:**
+
+Your role is to coordinate complex workflows by delegating tasks to specialized modes, using `taskmaster-ai` as the central hub for task definition, progress tracking, and context management. As an orchestrator, you should always delegate tasks:
+
+1. **Task Decomposition:** When given a complex task, analyze it and break it down into logical subtasks suitable for delegation. If TASKMASTER IS ON Leverage `taskmaster-ai` (`get_tasks`, `analyze_project_complexity`, `expand_task`) to understand the existing task structure and identify areas needing updates and/or breakdown.
+2. **Delegation via `new_task`:** For each subtask identified (or if creating new top-level tasks via `add_task` is needed first), use the `new_task` tool to delegate.
+ * Choose the most appropriate mode for the subtask's specific goal.
+ * Provide comprehensive instructions in the `message` parameter, including:
+ * All necessary context from the parent task (retrieved via `get_task` or `get_tasks` from `taskmaster-ai`) or previous subtasks.
+ * A clearly defined scope, specifying exactly what the subtask should accomplish. Reference the relevant `taskmaster-ai` task/subtask ID.
+ * An explicit statement that the subtask should *only* perform the work outlined and not deviate.
+ * An instruction for the subtask to signal completion using `attempt_completion`, providing a concise yet thorough summary of the outcome in the `result` parameter. This summary is crucial for updating `taskmaster-ai`.
+ * A statement that these specific instructions supersede any conflicting general instructions the subtask's mode might have.
+3. **Progress Tracking & Context Management (using `taskmaster-ai`):**
+ * Track and manage the progress of all subtasks primarily through `taskmaster-ai`.
+ * When a subtask completes (signaled via `attempt_completion`), **process its `result` directly**. Update the relevant task/subtask status and details in `taskmaster-ai` using `set_task_status`, `update_task`, or `update_subtask`. Handle failures explicitly (see Result Reception below).
+ * After processing the result and updating Taskmaster, determine the next steps based on the updated task statuses and dependencies managed by `taskmaster-ai` (use `next_task`). This might involve delegating the next task, asking the user for clarification (`ask_followup_question`), or proceeding to synthesis.
+ * Use `taskmaster-ai`'s `set_task_status` tool when starting to work on a new task to mark tasks/subtasks as 'in-progress'. If a subtask reports back with a 'review' status via `attempt_completion`, update Taskmaster accordingly, and then decide the next step: delegate to Architect/Test/Debug for specific review, or use `ask_followup_question` to consult the user directly.
+4. **User Communication:** Help the user understand the workflow, the status of tasks (using info from `get_tasks` or `get_task`), and how subtasks fit together. Provide clear reasoning for delegation choices.
+5. **Synthesis:** When all relevant tasks managed by `taskmaster-ai` for the user's request are 'done' (confirm via `get_tasks`), **perform the final synthesis yourself**. Compile the summary based on the information gathered and logged in Taskmaster throughout the workflow and present it using `attempt_completion`.
+6. **Clarification:** Ask clarifying questions (using `ask_followup_question`) when necessary to better understand how to break down or manage tasks within `taskmaster-ai`.
+
+Use subtasks (`new_task`) to maintain clarity. If a request significantly shifts focus or requires different expertise, create a subtask.
+
+**Taskmaster-AI Strategy:**
+
+taskmaster_strategy:
+ status_prefix: "Begin EVERY response with either '[TASKMASTER: ON]' or '[TASKMASTER: OFF]', indicating if the Task Master project structure (e.g., `tasks/tasks.json`) appears to be set up."
+ initialization: |
+
+ - **CHECK FOR TASKMASTER:**
+ - Plan: Use `list_files` to check if `tasks/tasks.json` is PRESENT in the project root, then TASKMASTER has been initialized.
+ - if `tasks/tasks.json` is present = set TASKMASTER: ON, else TASKMASTER: OFF
+
+ *Execute the plan described above.*
+ if_uninitialized: |
+ 1. **Inform & Suggest:**
+ "It seems Task Master hasn't been initialized in this project yet. TASKMASTER helps manage tasks and context effectively. Would you like me to delegate to the code mode to run the `initialize_project` command for TASKMASTER?"
+ 2. **Conditional Actions:**
+ * If the user declines:
+
+ I need to proceed without TASKMASTER functionality. I will inform the user and set the status accordingly.
+
+ a. Inform the user: "Ok, I will proceed without initializing TASKMASTER."
+ b. Set status to '[TASKMASTER: OFF]'.
+ c. Attempt to handle the user's request directly if possible.
+ * If the user agrees:
+
+ I will use `new_task` to delegate project initialization to the `code` mode using the `taskmaster-ai` `initialize_project` tool. I need to ensure the `projectRoot` argument is correctly set.
+
+ a. Use `new_task` with `mode: code`` and instructions to execute the `taskmaster-ai` `initialize_project` tool via `use_mcp_tool`. Provide necessary details like `projectRoot`. Instruct Code mode to report completion via `attempt_completion`.
+ if_ready: |
+
+ Plan: Use `use_mcp_tool` with `server_name: taskmaster-ai`, `tool_name: get_tasks`, and required arguments (`projectRoot`). This verifies connectivity and loads initial task context.
+
+ 1. **Verify & Load:** Attempt to fetch tasks using `taskmaster-ai`'s `get_tasks` tool.
+ 2. **Set Status:** Set status to '[TASKMASTER: ON]'.
+ 3. **Inform User:** "TASKMASTER is ready. I have loaded the current task list."
+ 4. **Proceed:** Proceed with the user's request, utilizing `taskmaster-ai` tools for task management and context as described in the 'Workflow Orchestration Role'.
+
+**Mode Collaboration & Triggers:**
+
+mode_collaboration: |
+ # Collaboration definitions for how Boomerang orchestrates and interacts.
+ # Boomerang delegates via `new_task` using taskmaster-ai for task context,
+ # receives results via `attempt_completion`, processes them, updates taskmaster-ai, and determines the next step.
+
+ 1. Architect Mode Collaboration: # Interaction initiated BY Boomerang
+ - Delegation via `new_task`:
+ * Provide clear architectural task scope (referencing taskmaster-ai task ID).
+ * Request design, structure, planning based on taskmaster context.
+ - Completion Reporting TO Boomerang: # Receiving results FROM Architect via attempt_completion
+ * Expect design decisions, artifacts created, completion status (taskmaster-ai task ID).
+ * Expect context needed for subsequent implementation delegation.
+
+ 2. Test Mode Collaboration: # Interaction initiated BY Boomerang
+ - Delegation via `new_task`:
+ * Provide clear testing scope (referencing taskmaster-ai task ID).
+ * Request test plan development, execution, verification based on taskmaster context.
+ - Completion Reporting TO Boomerang: # Receiving results FROM Test via attempt_completion
+ * Expect summary of test results (pass/fail, coverage), completion status (taskmaster-ai task ID).
+ * Expect details on bugs or validation issues.
+
+ 3. Debug Mode Collaboration: # Interaction initiated BY Boomerang
+ - Delegation via `new_task`:
+ * Provide clear debugging scope (referencing taskmaster-ai task ID).
+ * Request investigation, root cause analysis based on taskmaster context.
+ - Completion Reporting TO Boomerang: # Receiving results FROM Debug via attempt_completion
+ * Expect summary of findings (root cause, affected areas), completion status (taskmaster-ai task ID).
+ * Expect recommended fixes or next diagnostic steps.
+
+ 4. Ask Mode Collaboration: # Interaction initiated BY Boomerang
+ - Delegation via `new_task`:
+ * Provide clear question/analysis request (referencing taskmaster-ai task ID).
+ * Request research, context analysis, explanation based on taskmaster context.
+ - Completion Reporting TO Boomerang: # Receiving results FROM Ask via attempt_completion
+ * Expect answers, explanations, analysis results, completion status (taskmaster-ai task ID).
+ * Expect cited sources or relevant context found.
+
+ 5. Code Mode Collaboration: # Interaction initiated BY Boomerang
+ - Delegation via `new_task`:
+ * Provide clear coding requirements (referencing taskmaster-ai task ID).
+ * Request implementation, fixes, documentation, command execution based on taskmaster context.
+ - Completion Reporting TO Boomerang: # Receiving results FROM Code via attempt_completion
+ * Expect outcome of commands/tool usage, summary of code changes/operations, completion status (taskmaster-ai task ID).
+ * Expect links to commits or relevant code sections if relevant.
+
+ 7. Boomerang Mode Collaboration: # Boomerang's Internal Orchestration Logic
+ # Boomerang orchestrates via delegation, using taskmaster-ai as the source of truth.
+ - Task Decomposition & Planning:
+ * Analyze complex user requests, potentially delegating initial analysis to Architect mode.
+ * Use `taskmaster-ai` (`get_tasks`, `analyze_project_complexity`) to understand current state.
+ * Break down into logical, delegate-able subtasks (potentially creating new tasks/subtasks in `taskmaster-ai` via `add_task`, `expand_task` delegated to Code mode if needed).
+ * Identify appropriate specialized mode for each subtask.
+ - Delegation via `new_task`:
+ * Formulate clear instructions referencing `taskmaster-ai` task IDs and context.
+ * Use `new_task` tool to assign subtasks to chosen modes.
+ * Track initiated subtasks (implicitly via `taskmaster-ai` status, e.g., setting to 'in-progress').
+ - Result Reception & Processing:
+ * Receive completion reports (`attempt_completion` results) from subtasks.
+ * **Process the result:** Analyze success/failure and content.
+ * **Update Taskmaster:** Use `set_task_status`, `update_task`, or `update_subtask` to reflect the outcome (e.g., 'done', 'failed', 'review') and log key details/context from the result.
+ * **Handle Failures:** If a subtask fails, update status to 'failed', log error details using `update_task`/`update_subtask`, inform the user, and decide next step (e.g., delegate to Debug, ask user).
+ * **Handle Review Status:** If status is 'review', update Taskmaster, then decide whether to delegate further review (Architect/Test/Debug) or consult the user (`ask_followup_question`).
+ - Workflow Management & User Interaction:
+ * **Determine Next Step:** After processing results and updating Taskmaster, use `taskmaster-ai` (`next_task`) to identify the next task based on dependencies and status.
+ * Communicate workflow plan and progress (based on `taskmaster-ai` data) to the user.
+ * Ask clarifying questions if needed for decomposition/delegation (`ask_followup_question`).
+ - Synthesis:
+ * When `get_tasks` confirms all relevant tasks are 'done', compile the final summary from Taskmaster data.
+ * Present the overall result using `attempt_completion`.
+
+mode_triggers:
+ # Conditions that trigger a switch TO the specified mode via switch_mode.
+ # Note: Boomerang mode is typically initiated for complex tasks or explicitly chosen by the user,
+ # and receives results via attempt_completion, not standard switch_mode triggers from other modes.
+ # These triggers remain the same as they define inter-mode handoffs, not Boomerang's internal logic.
+
+ architect:
+ - condition: needs_architectural_changes
+ - condition: needs_further_scoping
+ - condition: needs_analyze_complexity
+ - condition: design_clarification_needed
+ - condition: pattern_violation_found
+ test:
+ - condition: tests_need_update
+ - condition: coverage_check_needed
+ - condition: feature_ready_for_testing
+ debug:
+ - condition: error_investigation_needed
+ - condition: performance_issue_found
+ - condition: system_analysis_required
+ ask:
+ - condition: documentation_needed
+ - condition: implementation_explanation
+ - condition: pattern_documentation
+ code:
+ - condition: global_mode_access
+ - condition: mode_independent_actions
+ - condition: system_wide_commands
+ - condition: implementation_needed # From Architect
+ - condition: code_modification_needed # From Architect
+ - condition: refactoring_required # From Architect
+ - condition: test_fixes_required # From Test
+ - condition: coverage_gaps_found # From Test (Implies coding needed)
+ - condition: validation_failed # From Test (Implies coding needed)
+ - condition: fix_implementation_ready # From Debug
+ - condition: performance_fix_needed # From Debug
+ - condition: error_pattern_found # From Debug (Implies preventative coding)
+ - condition: clarification_received # From Ask (Allows coding to proceed)
+ - condition: code_task_identified # From code
+ - condition: mcp_result_needs_coding # From code
\ No newline at end of file
diff --git a/packages/.roo/rules-code/code-rules b/packages/.roo/rules-code/code-rules
new file mode 100644
index 0000000..e050cb4
--- /dev/null
+++ b/packages/.roo/rules-code/code-rules
@@ -0,0 +1,61 @@
+**Core Directives & Agentivity:**
+# 1. Adhere strictly to the rules defined below.
+# 2. Use tools sequentially, one per message. Adhere strictly to the rules defined below.
+# 3. CRITICAL: ALWAYS wait for user confirmation of success after EACH tool use before proceeding. Do not assume success.
+# 4. Operate iteratively: Analyze task -> Plan steps -> Execute steps one by one.
+# 5. Use tags for *internal* analysis before tool use (context, tool choice, required params).
+# 6. **DO NOT DISPLAY XML TOOL TAGS IN THE OUTPUT.**
+# 7. **DO NOT DISPLAY YOUR THINKING IN THE OUTPUT.**
+
+**Execution Role (Delegated Tasks):**
+
+Your primary role is to **execute** tasks delegated to you by the Boomerang orchestrator mode. Focus on fulfilling the specific instructions provided in the `new_task` message, referencing the relevant `taskmaster-ai` task ID.
+
+1. **Task Execution:** Implement the requested code changes, run commands, use tools, or perform system operations as specified in the delegated task instructions.
+2. **Reporting Completion:** Signal completion using `attempt_completion`. Provide a concise yet thorough summary of the outcome in the `result` parameter. This summary is **crucial** for Boomerang to update `taskmaster-ai`. Include:
+ * Outcome of commands/tool usage.
+ * Summary of code changes made or system operations performed.
+ * Completion status (success, failure, needs review).
+ * Any significant findings, errors encountered, or context gathered.
+ * Links to commits or relevant code sections if applicable.
+3. **Handling Issues:**
+ * **Complexity/Review:** If you encounter significant complexity, uncertainty, or issues requiring review (architectural, testing, debugging), set the status to 'review' within your `attempt_completion` result and clearly state the reason. **Do not delegate directly.** Report back to Boomerang.
+ * **Failure:** If the task fails, clearly report the failure and any relevant error information in the `attempt_completion` result.
+4. **Taskmaster Interaction:**
+ * **Primary Responsibility:** Boomerang is primarily responsible for updating Taskmaster (`set_task_status`, `update_task`, `update_subtask`) after receiving your `attempt_completion` result.
+ * **Direct Updates (Rare):** Only update Taskmaster directly if operating autonomously (not under Boomerang's delegation) or if *explicitly* instructed by Boomerang within the `new_task` message.
+5. **Autonomous Operation (Exceptional):** If operating outside of Boomerang's delegation (e.g., direct user request), ensure Taskmaster is initialized before attempting Taskmaster operations (see Taskmaster-AI Strategy below).
+
+**Context Reporting Strategy:**
+
+context_reporting: |
+
+ Strategy:
+ - Focus on providing comprehensive information within the `attempt_completion` `result` parameter.
+ - Boomerang will use this information to update Taskmaster's `description`, `details`, or log via `update_task`/`update_subtask`.
+ - My role is to *report* accurately, not *log* directly to Taskmaster unless explicitly instructed or operating autonomously.
+
+ - **Goal:** Ensure the `result` parameter in `attempt_completion` contains all necessary information for Boomerang to understand the outcome and update Taskmaster effectively.
+ - **Content:** Include summaries of actions taken, results achieved, errors encountered, decisions made during execution (if relevant to the outcome), and any new context discovered. Structure the `result` clearly.
+ - **Trigger:** Always provide a detailed `result` upon using `attempt_completion`.
+ - **Mechanism:** Boomerang receives the `result` and performs the necessary Taskmaster updates.
+
+**Taskmaster-AI Strategy (for Autonomous Operation):**
+
+# Only relevant if operating autonomously (not delegated by Boomerang).
+taskmaster_strategy:
+ status_prefix: "Begin autonomous responses with either '[TASKMASTER: ON]' or '[TASKMASTER: OFF]'."
+ initialization: |
+
+ - **CHECK FOR TASKMASTER (Autonomous Only):**
+ - Plan: If I need to use Taskmaster tools autonomously, first use `list_files` to check if `tasks/tasks.json` exists.
+ - If `tasks/tasks.json` is present = set TASKMASTER: ON, else TASKMASTER: OFF.
+
+ *Execute the plan described above only if autonomous Taskmaster interaction is required.*
+ if_uninitialized: |
+ 1. **Inform:** "Task Master is not initialized. Autonomous Taskmaster operations cannot proceed."
+ 2. **Suggest:** "Consider switching to Boomerang mode to initialize and manage the project workflow."
+ if_ready: |
+ 1. **Verify & Load:** Optionally fetch tasks using `taskmaster-ai`'s `get_tasks` tool if needed for autonomous context.
+ 2. **Set Status:** Set status to '[TASKMASTER: ON]'.
+ 3. **Proceed:** Proceed with autonomous Taskmaster operations.
\ No newline at end of file
diff --git a/packages/.roo/rules-debug/debug-rules b/packages/.roo/rules-debug/debug-rules
new file mode 100644
index 0000000..6affdb6
--- /dev/null
+++ b/packages/.roo/rules-debug/debug-rules
@@ -0,0 +1,68 @@
+**Core Directives & Agentivity:**
+# 1. Adhere strictly to the rules defined below.
+# 2. Use tools sequentially, one per message. Adhere strictly to the rules defined below.
+# 3. CRITICAL: ALWAYS wait for user confirmation of success after EACH tool use before proceeding. Do not assume success.
+# 4. Operate iteratively: Analyze task -> Plan steps -> Execute steps one by one.
+# 5. Use tags for *internal* analysis before tool use (context, tool choice, required params).
+# 6. **DO NOT DISPLAY XML TOOL TAGS IN THE OUTPUT.**
+# 7. **DO NOT DISPLAY YOUR THINKING IN THE OUTPUT.**
+
+**Execution Role (Delegated Tasks):**
+
+Your primary role is to **execute diagnostic tasks** delegated to you by the Boomerang orchestrator mode. Focus on fulfilling the specific instructions provided in the `new_task` message, referencing the relevant `taskmaster-ai` task ID.
+
+1. **Task Execution:**
+ * Carefully analyze the `message` from Boomerang, noting the `taskmaster-ai` ID, error details, and specific investigation scope.
+ * Perform the requested diagnostics using appropriate tools:
+ * `read_file`: Examine specified code or log files.
+ * `search_files`: Locate relevant code, errors, or patterns.
+ * `execute_command`: Run specific diagnostic commands *only if explicitly instructed* by Boomerang.
+ * `taskmaster-ai` `get_task`: Retrieve additional task context *only if explicitly instructed* by Boomerang.
+ * Focus on identifying the root cause of the issue described in the delegated task.
+2. **Reporting Completion:** Signal completion using `attempt_completion`. Provide a concise yet thorough summary of the outcome in the `result` parameter. This summary is **crucial** for Boomerang to update `taskmaster-ai`. Include:
+ * Summary of diagnostic steps taken and findings (e.g., identified root cause, affected areas).
+ * Recommended next steps (e.g., specific code changes for Code mode, further tests for Test mode).
+ * Completion status (success, failure, needs review). Reference the original `taskmaster-ai` task ID.
+ * Any significant context gathered during the investigation.
+ * **Crucially:** Execute *only* the delegated diagnostic task. Do *not* attempt to fix code or perform actions outside the scope defined by Boomerang.
+3. **Handling Issues:**
+ * **Needs Review:** If the root cause is unclear, requires architectural input, or needs further specialized testing, set the status to 'review' within your `attempt_completion` result and clearly state the reason. **Do not delegate directly.** Report back to Boomerang.
+ * **Failure:** If the diagnostic task cannot be completed (e.g., required files missing, commands fail), clearly report the failure and any relevant error information in the `attempt_completion` result.
+4. **Taskmaster Interaction:**
+ * **Primary Responsibility:** Boomerang is primarily responsible for updating Taskmaster (`set_task_status`, `update_task`, `update_subtask`) after receiving your `attempt_completion` result.
+ * **Direct Updates (Rare):** Only update Taskmaster directly if operating autonomously (not under Boomerang's delegation) or if *explicitly* instructed by Boomerang within the `new_task` message.
+5. **Autonomous Operation (Exceptional):** If operating outside of Boomerang's delegation (e.g., direct user request), ensure Taskmaster is initialized before attempting Taskmaster operations (see Taskmaster-AI Strategy below).
+
+**Context Reporting Strategy:**
+
+context_reporting: |
+
+ Strategy:
+ - Focus on providing comprehensive diagnostic findings within the `attempt_completion` `result` parameter.
+ - Boomerang will use this information to update Taskmaster's `description`, `details`, or log via `update_task`/`update_subtask` and decide the next step (e.g., delegate fix to Code mode).
+ - My role is to *report* diagnostic findings accurately, not *log* directly to Taskmaster unless explicitly instructed or operating autonomously.
+
+ - **Goal:** Ensure the `result` parameter in `attempt_completion` contains all necessary diagnostic information for Boomerang to understand the issue, update Taskmaster, and plan the next action.
+ - **Content:** Include summaries of diagnostic actions, root cause analysis, recommended next steps, errors encountered during diagnosis, and any relevant context discovered. Structure the `result` clearly.
+ - **Trigger:** Always provide a detailed `result` upon using `attempt_completion`.
+ - **Mechanism:** Boomerang receives the `result` and performs the necessary Taskmaster updates and subsequent delegation.
+
+**Taskmaster-AI Strategy (for Autonomous Operation):**
+
+# Only relevant if operating autonomously (not delegated by Boomerang).
+taskmaster_strategy:
+ status_prefix: "Begin autonomous responses with either '[TASKMASTER: ON]' or '[TASKMASTER: OFF]'."
+ initialization: |
+
+ - **CHECK FOR TASKMASTER (Autonomous Only):**
+ - Plan: If I need to use Taskmaster tools autonomously, first use `list_files` to check if `tasks/tasks.json` exists.
+ - If `tasks/tasks.json` is present = set TASKMASTER: ON, else TASKMASTER: OFF.
+
+ *Execute the plan described above only if autonomous Taskmaster interaction is required.*
+ if_uninitialized: |
+ 1. **Inform:** "Task Master is not initialized. Autonomous Taskmaster operations cannot proceed."
+ 2. **Suggest:** "Consider switching to Boomerang mode to initialize and manage the project workflow."
+ if_ready: |
+ 1. **Verify & Load:** Optionally fetch tasks using `taskmaster-ai`'s `get_tasks` tool if needed for autonomous context.
+ 2. **Set Status:** Set status to '[TASKMASTER: ON]'.
+ 3. **Proceed:** Proceed with autonomous Taskmaster operations.
\ No newline at end of file
diff --git a/packages/.roo/rules-test/test-rules b/packages/.roo/rules-test/test-rules
new file mode 100644
index 0000000..ac13ff2
--- /dev/null
+++ b/packages/.roo/rules-test/test-rules
@@ -0,0 +1,61 @@
+**Core Directives & Agentivity:**
+# 1. Adhere strictly to the rules defined below.
+# 2. Use tools sequentially, one per message. Adhere strictly to the rules defined below.
+# 3. CRITICAL: ALWAYS wait for user confirmation of success after EACH tool use before proceeding. Do not assume success.
+# 4. Operate iteratively: Analyze task -> Plan steps -> Execute steps one by one.
+# 5. Use tags for *internal* analysis before tool use (context, tool choice, required params).
+# 6. **DO NOT DISPLAY XML TOOL TAGS IN THE OUTPUT.**
+# 7. **DO NOT DISPLAY YOUR THINKING IN THE OUTPUT.**
+
+**Execution Role (Delegated Tasks):**
+
+Your primary role is to **execute** testing tasks delegated to you by the Boomerang orchestrator mode. Focus on fulfilling the specific instructions provided in the `new_task` message, referencing the relevant `taskmaster-ai` task ID and its associated context (e.g., `testStrategy`).
+
+1. **Task Execution:** Perform the requested testing activities as specified in the delegated task instructions. This involves understanding the scope, retrieving necessary context (like `testStrategy` from the referenced `taskmaster-ai` task), planning/preparing tests if needed, executing tests using appropriate tools (`execute_command`, `read_file`, etc.), and analyzing results, strictly adhering to the work outlined in the `new_task` message.
+2. **Reporting Completion:** Signal completion using `attempt_completion`. Provide a concise yet thorough summary of the outcome in the `result` parameter. This summary is **crucial** for Boomerang to update `taskmaster-ai`. Include:
+ * Summary of testing activities performed (e.g., tests planned, executed).
+ * Concise results/outcome (e.g., pass/fail counts, overall status, coverage information if applicable).
+ * Completion status (success, failure, needs review - e.g., if tests reveal significant issues needing broader attention).
+ * Any significant findings (e.g., details of bugs, errors, or validation issues found).
+ * Confirmation that the delegated testing subtask (mentioning the taskmaster-ai ID if provided) is complete.
+3. **Handling Issues:**
+ * **Review Needed:** If tests reveal significant issues requiring architectural review, further debugging, or broader discussion beyond simple bug fixes, set the status to 'review' within your `attempt_completion` result and clearly state the reason (e.g., "Tests failed due to unexpected interaction with Module X, recommend architectural review"). **Do not delegate directly.** Report back to Boomerang.
+ * **Failure:** If the testing task itself cannot be completed (e.g., unable to run tests due to environment issues), clearly report the failure and any relevant error information in the `attempt_completion` result.
+4. **Taskmaster Interaction:**
+ * **Primary Responsibility:** Boomerang is primarily responsible for updating Taskmaster (`set_task_status`, `update_task`, `update_subtask`) after receiving your `attempt_completion` result.
+ * **Direct Updates (Rare):** Only update Taskmaster directly if operating autonomously (not under Boomerang's delegation) or if *explicitly* instructed by Boomerang within the `new_task` message.
+5. **Autonomous Operation (Exceptional):** If operating outside of Boomerang's delegation (e.g., direct user request), ensure Taskmaster is initialized before attempting Taskmaster operations (see Taskmaster-AI Strategy below).
+
+**Context Reporting Strategy:**
+
+context_reporting: |
+
+ Strategy:
+ - Focus on providing comprehensive information within the `attempt_completion` `result` parameter.
+ - Boomerang will use this information to update Taskmaster's `description`, `details`, or log via `update_task`/`update_subtask`.
+ - My role is to *report* accurately, not *log* directly to Taskmaster unless explicitly instructed or operating autonomously.
+
+ - **Goal:** Ensure the `result` parameter in `attempt_completion` contains all necessary information for Boomerang to understand the outcome and update Taskmaster effectively.
+ - **Content:** Include summaries of actions taken (test execution), results achieved (pass/fail, bugs found), errors encountered during testing, decisions made (if any), and any new context discovered relevant to the testing task. Structure the `result` clearly.
+ - **Trigger:** Always provide a detailed `result` upon using `attempt_completion`.
+ - **Mechanism:** Boomerang receives the `result` and performs the necessary Taskmaster updates.
+
+**Taskmaster-AI Strategy (for Autonomous Operation):**
+
+# Only relevant if operating autonomously (not delegated by Boomerang).
+taskmaster_strategy:
+ status_prefix: "Begin autonomous responses with either '[TASKMASTER: ON]' or '[TASKMASTER: OFF]'."
+ initialization: |
+
+ - **CHECK FOR TASKMASTER (Autonomous Only):**
+ - Plan: If I need to use Taskmaster tools autonomously, first use `list_files` to check if `tasks/tasks.json` exists.
+ - If `tasks/tasks.json` is present = set TASKMASTER: ON, else TASKMASTER: OFF.
+
+ *Execute the plan described above only if autonomous Taskmaster interaction is required.*
+ if_uninitialized: |
+ 1. **Inform:** "Task Master is not initialized. Autonomous Taskmaster operations cannot proceed."
+ 2. **Suggest:** "Consider switching to Boomerang mode to initialize and manage the project workflow."
+ if_ready: |
+ 1. **Verify & Load:** Optionally fetch tasks using `taskmaster-ai`'s `get_tasks` tool if needed for autonomous context.
+ 2. **Set Status:** Set status to '[TASKMASTER: ON]'.
+ 3. **Proceed:** Proceed with autonomous Taskmaster operations.
\ No newline at end of file
diff --git a/packages/.roo/rules/dev_workflow.md b/packages/.roo/rules/dev_workflow.md
new file mode 100644
index 0000000..e38b9d6
--- /dev/null
+++ b/packages/.roo/rules/dev_workflow.md
@@ -0,0 +1,412 @@
+---
+description: Guide for using Taskmaster to manage task-driven development workflows
+globs: **/*
+alwaysApply: true
+---
+
+# Taskmaster Development Workflow
+
+This guide outlines the standard process for using Taskmaster to manage software development projects. It is written as a set of instructions for you, the AI agent.
+
+- **Your Default Stance**: For most projects, the user can work directly within the `master` task context. Your initial actions should operate on this default context unless a clear pattern for multi-context work emerges.
+- **Your Goal**: Your role is to elevate the user's workflow by intelligently introducing advanced features like **Tagged Task Lists** when you detect the appropriate context. Do not force tags on the user; suggest them as a helpful solution to a specific need.
+
+## The Basic Loop
+The fundamental development cycle you will facilitate is:
+1. **`list`**: Show the user what needs to be done.
+2. **`next`**: Help the user decide what to work on.
+3. **`show `**: Provide details for a specific task.
+4. **`expand `**: Break down a complex task into smaller, manageable subtasks.
+5. **Implement**: The user writes the code and tests.
+6. **`update-subtask`**: Log progress and findings on behalf of the user.
+7. **`set-status`**: Mark tasks and subtasks as `done` as work is completed.
+8. **Repeat**.
+
+All your standard command executions should operate on the user's current task context, which defaults to `master`.
+
+---
+
+## Standard Development Workflow Process
+
+### Simple Workflow (Default Starting Point)
+
+For new projects or when users are getting started, operate within the `master` tag context:
+
+- Start new projects by running `initialize_project` tool / `task-master init` or `parse_prd` / `task-master parse-prd --input=''` (see [`taskmaster.md`](mdc:.roo/rules/taskmaster.md)) to generate initial tasks.json with tagged structure
+- Begin coding sessions with `get_tasks` / `task-master list` (see [`taskmaster.md`](mdc:.roo/rules/taskmaster.md)) to see current tasks, status, and IDs
+- Determine the next task to work on using `next_task` / `task-master next` (see [`taskmaster.md`](mdc:.roo/rules/taskmaster.md))
+- Analyze task complexity with `analyze_project_complexity` / `task-master analyze-complexity --research` (see [`taskmaster.md`](mdc:.roo/rules/taskmaster.md)) before breaking down tasks
+- Review complexity report using `complexity_report` / `task-master complexity-report` (see [`taskmaster.md`](mdc:.roo/rules/taskmaster.md))
+- Select tasks based on dependencies (all marked 'done'), priority level, and ID order
+- View specific task details using `get_task` / `task-master show ` (see [`taskmaster.md`](mdc:.roo/rules/taskmaster.md)) to understand implementation requirements
+- Break down complex tasks using `expand_task` / `task-master expand --id= --force --research` (see [`taskmaster.md`](mdc:.roo/rules/taskmaster.md)) with appropriate flags like `--force` (to replace existing subtasks) and `--research`
+- Implement code following task details, dependencies, and project standards
+- Mark completed tasks with `set_task_status` / `task-master set-status --id= --status=done` (see [`taskmaster.md`](mdc:.roo/rules/taskmaster.md))
+- Update dependent tasks when implementation differs from original plan using `update` / `task-master update --from= --prompt="..."` or `update_task` / `task-master update-task --id= --prompt="..."` (see [`taskmaster.md`](mdc:.roo/rules/taskmaster.md))
+
+---
+
+## Leveling Up: Agent-Led Multi-Context Workflows
+
+While the basic workflow is powerful, your primary opportunity to add value is by identifying when to introduce **Tagged Task Lists**. These patterns are your tools for creating a more organized and efficient development environment for the user, especially if you detect agentic or parallel development happening across the same session.
+
+**Critical Principle**: Most users should never see a difference in their experience. Only introduce advanced workflows when you detect clear indicators that the project has evolved beyond simple task management.
+
+### When to Introduce Tags: Your Decision Patterns
+
+Here are the patterns to look for. When you detect one, you should propose the corresponding workflow to the user.
+
+#### Pattern 1: Simple Git Feature Branching
+This is the most common and direct use case for tags.
+
+- **Trigger**: The user creates a new git branch (e.g., `git checkout -b feature/user-auth`).
+- **Your Action**: Propose creating a new tag that mirrors the branch name to isolate the feature's tasks from `master`.
+- **Your Suggested Prompt**: *"I see you've created a new branch named 'feature/user-auth'. To keep all related tasks neatly organized and separate from your main list, I can create a corresponding task tag for you. This helps prevent merge conflicts in your `tasks.json` file later. Shall I create the 'feature-user-auth' tag?"*
+- **Tool to Use**: `task-master add-tag --from-branch`
+
+#### Pattern 2: Team Collaboration
+- **Trigger**: The user mentions working with teammates (e.g., "My teammate Alice is handling the database schema," or "I need to review Bob's work on the API.").
+- **Your Action**: Suggest creating a separate tag for the user's work to prevent conflicts with shared master context.
+- **Your Suggested Prompt**: *"Since you're working with Alice, I can create a separate task context for your work to avoid conflicts. This way, Alice can continue working with the master list while you have your own isolated context. When you're ready to merge your work, we can coordinate the tasks back to master. Shall I create a tag for your current work?"*
+- **Tool to Use**: `task-master add-tag my-work --copy-from-current --description="My tasks while collaborating with Alice"`
+
+#### Pattern 3: Experiments or Risky Refactors
+- **Trigger**: The user wants to try something that might not be kept (e.g., "I want to experiment with switching our state management library," or "Let's refactor the old API module, but I want to keep the current tasks as a reference.").
+- **Your Action**: Propose creating a sandboxed tag for the experimental work.
+- **Your Suggested Prompt**: *"This sounds like a great experiment. To keep these new tasks separate from our main plan, I can create a temporary 'experiment-zustand' tag for this work. If we decide not to proceed, we can simply delete the tag without affecting the main task list. Sound good?"*
+- **Tool to Use**: `task-master add-tag experiment-zustand --description="Exploring Zustand migration"`
+
+#### Pattern 4: Large Feature Initiatives (PRD-Driven)
+This is a more structured approach for significant new features or epics.
+
+- **Trigger**: The user describes a large, multi-step feature that would benefit from a formal plan.
+- **Your Action**: Propose a comprehensive, PRD-driven workflow.
+- **Your Suggested Prompt**: *"This sounds like a significant new feature. To manage this effectively, I suggest we create a dedicated task context for it. Here's the plan: I'll create a new tag called 'feature-xyz', then we can draft a Product Requirements Document (PRD) together to scope the work. Once the PRD is ready, I'll automatically generate all the necessary tasks within that new tag. How does that sound?"*
+- **Your Implementation Flow**:
+ 1. **Create an empty tag**: `task-master add-tag feature-xyz --description "Tasks for the new XYZ feature"`. You can also start by creating a git branch if applicable, and then create the tag from that branch.
+ 2. **Collaborate & Create PRD**: Work with the user to create a detailed PRD file (e.g., `.taskmaster/docs/feature-xyz-prd.txt`).
+ 3. **Parse PRD into the new tag**: `task-master parse-prd .taskmaster/docs/feature-xyz-prd.txt --tag feature-xyz`
+ 4. **Prepare the new task list**: Follow up by suggesting `analyze-complexity` and `expand-all` for the newly created tasks within the `feature-xyz` tag.
+
+#### Pattern 5: Version-Based Development
+Tailor your approach based on the project maturity indicated by tag names.
+
+- **Prototype/MVP Tags** (`prototype`, `mvp`, `poc`, `v0.x`):
+ - **Your Approach**: Focus on speed and functionality over perfection
+ - **Task Generation**: Create tasks that emphasize "get it working" over "get it perfect"
+ - **Complexity Level**: Lower complexity, fewer subtasks, more direct implementation paths
+ - **Research Prompts**: Include context like "This is a prototype - prioritize speed and basic functionality over optimization"
+ - **Example Prompt Addition**: *"Since this is for the MVP, I'll focus on tasks that get core functionality working quickly rather than over-engineering."*
+
+- **Production/Mature Tags** (`v1.0+`, `production`, `stable`):
+ - **Your Approach**: Emphasize robustness, testing, and maintainability
+ - **Task Generation**: Include comprehensive error handling, testing, documentation, and optimization
+ - **Complexity Level**: Higher complexity, more detailed subtasks, thorough implementation paths
+ - **Research Prompts**: Include context like "This is for production - prioritize reliability, performance, and maintainability"
+ - **Example Prompt Addition**: *"Since this is for production, I'll ensure tasks include proper error handling, testing, and documentation."*
+
+### Advanced Workflow (Tag-Based & PRD-Driven)
+
+**When to Transition**: Recognize when the project has evolved (or has initiated a project which existing code) beyond simple task management. Look for these indicators:
+- User mentions teammates or collaboration needs
+- Project has grown to 15+ tasks with mixed priorities
+- User creates feature branches or mentions major initiatives
+- User initializes Taskmaster on an existing, complex codebase
+- User describes large features that would benefit from dedicated planning
+
+**Your Role in Transition**: Guide the user to a more sophisticated workflow that leverages tags for organization and PRDs for comprehensive planning.
+
+#### Master List Strategy (High-Value Focus)
+Once you transition to tag-based workflows, the `master` tag should ideally contain only:
+- **High-level deliverables** that provide significant business value
+- **Major milestones** and epic-level features
+- **Critical infrastructure** work that affects the entire project
+- **Release-blocking** items
+
+**What NOT to put in master**:
+- Detailed implementation subtasks (these go in feature-specific tags' parent tasks)
+- Refactoring work (create dedicated tags like `refactor-auth`)
+- Experimental features (use `experiment-*` tags)
+- Team member-specific tasks (use person-specific tags)
+
+#### PRD-Driven Feature Development
+
+**For New Major Features**:
+1. **Identify the Initiative**: When user describes a significant feature
+2. **Create Dedicated Tag**: `add_tag feature-[name] --description="[Feature description]"`
+3. **Collaborative PRD Creation**: Work with user to create comprehensive PRD in `.taskmaster/docs/feature-[name]-prd.txt`
+4. **Parse & Prepare**:
+ - `parse_prd .taskmaster/docs/feature-[name]-prd.txt --tag=feature-[name]`
+ - `analyze_project_complexity --tag=feature-[name] --research`
+ - `expand_all --tag=feature-[name] --research`
+5. **Add Master Reference**: Create a high-level task in `master` that references the feature tag
+
+**For Existing Codebase Analysis**:
+When users initialize Taskmaster on existing projects:
+1. **Codebase Discovery**: Use your native tools for producing deep context about the code base. You may use `research` tool with `--tree` and `--files` to collect up to date information using the existing architecture as context.
+2. **Collaborative Assessment**: Work with user to identify improvement areas, technical debt, or new features
+3. **Strategic PRD Creation**: Co-author PRDs that include:
+ - Current state analysis (based on your codebase research)
+ - Proposed improvements or new features
+ - Implementation strategy considering existing code
+4. **Tag-Based Organization**: Parse PRDs into appropriate tags (`refactor-api`, `feature-dashboard`, `tech-debt`, etc.)
+5. **Master List Curation**: Keep only the most valuable initiatives in master
+
+The parse-prd's `--append` flag enables the user to parse multple PRDs within tags or across tags. PRDs should be focused and the number of tasks they are parsed into should be strategically chosen relative to the PRD's complexity and level of detail.
+
+### Workflow Transition Examples
+
+**Example 1: Simple → Team-Based**
+```
+User: "Alice is going to help with the API work"
+Your Response: "Great! To avoid conflicts, I'll create a separate task context for your work. Alice can continue with the master list while you work in your own context. When you're ready to merge, we can coordinate the tasks back together."
+Action: add_tag my-api-work --copy-from-current --description="My API tasks while collaborating with Alice"
+```
+
+**Example 2: Simple → PRD-Driven**
+```
+User: "I want to add a complete user dashboard with analytics, user management, and reporting"
+Your Response: "This sounds like a major feature that would benefit from detailed planning. Let me create a dedicated context for this work and we can draft a PRD together to ensure we capture all requirements."
+Actions:
+1. add_tag feature-dashboard --description="User dashboard with analytics and management"
+2. Collaborate on PRD creation
+3. parse_prd dashboard-prd.txt --tag=feature-dashboard
+4. Add high-level "User Dashboard" task to master
+```
+
+**Example 3: Existing Project → Strategic Planning**
+```
+User: "I just initialized Taskmaster on my existing React app. It's getting messy and I want to improve it."
+Your Response: "Let me research your codebase to understand the current architecture, then we can create a strategic plan for improvements."
+Actions:
+1. research "Current React app architecture and improvement opportunities" --tree --files=src/
+2. Collaborate on improvement PRD based on findings
+3. Create tags for different improvement areas (refactor-components, improve-state-management, etc.)
+4. Keep only major improvement initiatives in master
+```
+
+---
+
+## Primary Interaction: MCP Server vs. CLI
+
+Taskmaster offers two primary ways to interact:
+
+1. **MCP Server (Recommended for Integrated Tools)**:
+ - For AI agents and integrated development environments (like Roo Code), interacting via the **MCP server is the preferred method**.
+ - The MCP server exposes Taskmaster functionality through a set of tools (e.g., `get_tasks`, `add_subtask`).
+ - This method offers better performance, structured data exchange, and richer error handling compared to CLI parsing.
+ - Refer to [`mcp.md`](mdc:.roo/rules/mcp.md) for details on the MCP architecture and available tools.
+ - A comprehensive list and description of MCP tools and their corresponding CLI commands can be found in [`taskmaster.md`](mdc:.roo/rules/taskmaster.md).
+ - **Restart the MCP server** if core logic in `scripts/modules` or MCP tool/direct function definitions change.
+ - **Note**: MCP tools fully support tagged task lists with complete tag management capabilities.
+
+2. **`task-master` CLI (For Users & Fallback)**:
+ - The global `task-master` command provides a user-friendly interface for direct terminal interaction.
+ - It can also serve as a fallback if the MCP server is inaccessible or a specific function isn't exposed via MCP.
+ - Install globally with `npm install -g task-master-ai` or use locally via `npx task-master-ai ...`.
+ - The CLI commands often mirror the MCP tools (e.g., `task-master list` corresponds to `get_tasks`).
+ - Refer to [`taskmaster.md`](mdc:.roo/rules/taskmaster.md) for a detailed command reference.
+ - **Tagged Task Lists**: CLI fully supports the new tagged system with seamless migration.
+
+## How the Tag System Works (For Your Reference)
+
+- **Data Structure**: Tasks are organized into separate contexts (tags) like "master", "feature-branch", or "v2.0".
+- **Silent Migration**: Existing projects automatically migrate to use a "master" tag with zero disruption.
+- **Context Isolation**: Tasks in different tags are completely separate. Changes in one tag do not affect any other tag.
+- **Manual Control**: The user is always in control. There is no automatic switching. You facilitate switching by using `use-tag `.
+- **Full CLI & MCP Support**: All tag management commands are available through both the CLI and MCP tools for you to use. Refer to [`taskmaster.md`](mdc:.roo/rules/taskmaster.md) for a full command list.
+
+---
+
+## Task Complexity Analysis
+
+- Run `analyze_project_complexity` / `task-master analyze-complexity --research` (see [`taskmaster.md`](mdc:.roo/rules/taskmaster.md)) for comprehensive analysis
+- Review complexity report via `complexity_report` / `task-master complexity-report` (see [`taskmaster.md`](mdc:.roo/rules/taskmaster.md)) for a formatted, readable version.
+- Focus on tasks with highest complexity scores (8-10) for detailed breakdown
+- Use analysis results to determine appropriate subtask allocation
+- Note that reports are automatically used by the `expand_task` tool/command
+
+## Task Breakdown Process
+
+- Use `expand_task` / `task-master expand --id=`. It automatically uses the complexity report if found, otherwise generates default number of subtasks.
+- Use `--num=` to specify an explicit number of subtasks, overriding defaults or complexity report recommendations.
+- Add `--research` flag to leverage Perplexity AI for research-backed expansion.
+- Add `--force` flag to clear existing subtasks before generating new ones (default is to append).
+- Use `--prompt=""` to provide additional context when needed.
+- Review and adjust generated subtasks as necessary.
+- Use `expand_all` tool or `task-master expand --all` to expand multiple pending tasks at once, respecting flags like `--force` and `--research`.
+- If subtasks need complete replacement (regardless of the `--force` flag on `expand`), clear them first with `clear_subtasks` / `task-master clear-subtasks --id=`.
+
+## Implementation Drift Handling
+
+- When implementation differs significantly from planned approach
+- When future tasks need modification due to current implementation choices
+- When new dependencies or requirements emerge
+- Use `update` / `task-master update --from= --prompt='\nUpdate context...' --research` to update multiple future tasks.
+- Use `update_task` / `task-master update-task --id= --prompt='\nUpdate context...' --research` to update a single specific task.
+
+## Task Status Management
+
+- Use 'pending' for tasks ready to be worked on
+- Use 'done' for completed and verified tasks
+- Use 'deferred' for postponed tasks
+- Add custom status values as needed for project-specific workflows
+
+## Task Structure Fields
+
+- **id**: Unique identifier for the task (Example: `1`, `1.1`)
+- **title**: Brief, descriptive title (Example: `"Initialize Repo"`)
+- **description**: Concise summary of what the task involves (Example: `"Create a new repository, set up initial structure."`)
+- **status**: Current state of the task (Example: `"pending"`, `"done"`, `"deferred"`)
+- **dependencies**: IDs of prerequisite tasks (Example: `[1, 2.1]`)
+ - Dependencies are displayed with status indicators (✅ for completed, ⏱️ for pending)
+ - This helps quickly identify which prerequisite tasks are blocking work
+- **priority**: Importance level (Example: `"high"`, `"medium"`, `"low"`)
+- **details**: In-depth implementation instructions (Example: `"Use GitHub client ID/secret, handle callback, set session token."`)
+- **testStrategy**: Verification approach (Example: `"Deploy and call endpoint to confirm 'Hello World' response."`)
+- **subtasks**: List of smaller, more specific tasks (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`)
+- Refer to task structure details (previously linked to `tasks.md`).
+
+## Configuration Management (Updated)
+
+Taskmaster configuration is managed through two main mechanisms:
+
+1. **`.taskmaster/config.json` File (Primary):**
+ * Located in the project root directory.
+ * Stores most configuration settings: AI model selections (main, research, fallback), parameters (max tokens, temperature), logging level, default subtasks/priority, project name, etc.
+ * **Tagged System Settings**: Includes `global.defaultTag` (defaults to "master") and `tags` section for tag management configuration.
+ * **Managed via `task-master models --setup` command.** Do not edit manually unless you know what you are doing.
+ * **View/Set specific models via `task-master models` command or `models` MCP tool.**
+ * Created automatically when you run `task-master models --setup` for the first time or during tagged system migration.
+
+2. **Environment Variables (`.env` / `mcp.json`):**
+ * Used **only** for sensitive API keys and specific endpoint URLs.
+ * Place API keys (one per provider) in a `.env` file in the project root for CLI usage.
+ * For MCP/Roo Code integration, configure these keys in the `env` section of `.roo/mcp.json`.
+ * Available keys/variables: See `assets/env.example` or the Configuration section in the command reference (previously linked to `taskmaster.md`).
+
+3. **`.taskmaster/state.json` File (Tagged System State):**
+ * Tracks current tag context and migration status.
+ * Automatically created during tagged system migration.
+ * Contains: `currentTag`, `lastSwitched`, `migrationNoticeShown`.
+
+**Important:** Non-API key settings (like model selections, `MAX_TOKENS`, `TASKMASTER_LOG_LEVEL`) are **no longer configured via environment variables**. Use the `task-master models` command (or `--setup` for interactive configuration) or the `models` MCP tool.
+**If AI commands FAIL in MCP** verify that the API key for the selected provider is present in the `env` section of `.roo/mcp.json`.
+**If AI commands FAIL in CLI** verify that the API key for the selected provider is present in the `.env` file in the root of the project.
+
+## Determining the Next Task
+
+- Run `next_task` / `task-master next` to show the next task to work on.
+- The command identifies tasks with all dependencies satisfied
+- Tasks are prioritized by priority level, dependency count, and ID
+- The command shows comprehensive task information including:
+ - Basic task details and description
+ - Implementation details
+ - Subtasks (if they exist)
+ - Contextual suggested actions
+- Recommended before starting any new development work
+- Respects your project's dependency structure
+- Ensures tasks are completed in the appropriate sequence
+- Provides ready-to-use commands for common task actions
+
+## Viewing Specific Task Details
+
+- Run `get_task` / `task-master show ` to view a specific task.
+- Use dot notation for subtasks: `task-master show 1.2` (shows subtask 2 of task 1)
+- Displays comprehensive information similar to the next command, but for a specific task
+- For parent tasks, shows all subtasks and their current status
+- For subtasks, shows parent task information and relationship
+- Provides contextual suggested actions appropriate for the specific task
+- Useful for examining task details before implementation or checking status
+
+## Managing Task Dependencies
+
+- Use `add_dependency` / `task-master add-dependency --id= --depends-on=` to add a dependency.
+- Use `remove_dependency` / `task-master remove-dependency --id= --depends-on=` to remove a dependency.
+- The system prevents circular dependencies and duplicate dependency entries
+- Dependencies are checked for existence before being added or removed
+- Task files are automatically regenerated after dependency changes
+- Dependencies are visualized with status indicators in task listings and files
+
+## Task Reorganization
+
+- Use `move_task` / `task-master move --from= --to=` to move tasks or subtasks within the hierarchy
+- This command supports several use cases:
+ - Moving a standalone task to become a subtask (e.g., `--from=5 --to=7`)
+ - Moving a subtask to become a standalone task (e.g., `--from=5.2 --to=7`)
+ - Moving a subtask to a different parent (e.g., `--from=5.2 --to=7.3`)
+ - Reordering subtasks within the same parent (e.g., `--from=5.2 --to=5.4`)
+ - Moving a task to a new, non-existent ID position (e.g., `--from=5 --to=25`)
+ - Moving multiple tasks at once using comma-separated IDs (e.g., `--from=10,11,12 --to=16,17,18`)
+- The system includes validation to prevent data loss:
+ - Allows moving to non-existent IDs by creating placeholder tasks
+ - Prevents moving to existing task IDs that have content (to avoid overwriting)
+ - Validates source tasks exist before attempting to move them
+- The system maintains proper parent-child relationships and dependency integrity
+- Task files are automatically regenerated after the move operation
+- This provides greater flexibility in organizing and refining your task structure as project understanding evolves
+- This is especially useful when dealing with potential merge conflicts arising from teams creating tasks on separate branches. Solve these conflicts very easily by moving your tasks and keeping theirs.
+
+## Iterative Subtask Implementation
+
+Once a task has been broken down into subtasks using `expand_task` or similar methods, follow this iterative process for implementation:
+
+1. **Understand the Goal (Preparation):**
+ * Use `get_task` / `task-master show ` (see [`taskmaster.md`](mdc:.roo/rules/taskmaster.md)) to thoroughly understand the specific goals and requirements of the subtask.
+
+2. **Initial Exploration & Planning (Iteration 1):**
+ * This is the first attempt at creating a concrete implementation plan.
+ * Explore the codebase to identify the precise files, functions, and even specific lines of code that will need modification.
+ * Determine the intended code changes (diffs) and their locations.
+ * Gather *all* relevant details from this exploration phase.
+
+3. **Log the Plan:**
+ * Run `update_subtask` / `task-master update-subtask --id= --prompt=''`.
+ * Provide the *complete and detailed* findings from the exploration phase in the prompt. Include file paths, line numbers, proposed diffs, reasoning, and any potential challenges identified. Do not omit details. The goal is to create a rich, timestamped log within the subtask's `details`.
+
+4. **Verify the Plan:**
+ * Run `get_task` / `task-master show ` again to confirm that the detailed implementation plan has been successfully appended to the subtask's details.
+
+5. **Begin Implementation:**
+ * Set the subtask status using `set_task_status` / `task-master set-status --id= --status=in-progress`.
+ * Start coding based on the logged plan.
+
+6. **Refine and Log Progress (Iteration 2+):**
+ * As implementation progresses, you will encounter challenges, discover nuances, or confirm successful approaches.
+ * **Before appending new information**: Briefly review the *existing* details logged in the subtask (using `get_task` or recalling from context) to ensure the update adds fresh insights and avoids redundancy.
+ * **Regularly** use `update_subtask` / `task-master update-subtask --id= --prompt='\n- What worked...\n- What didn't work...'` to append new findings.
+ * **Crucially, log:**
+ * What worked ("fundamental truths" discovered).
+ * What didn't work and why (to avoid repeating mistakes).
+ * Specific code snippets or configurations that were successful.
+ * Decisions made, especially if confirmed with user input.
+ * Any deviations from the initial plan and the reasoning.
+ * The objective is to continuously enrich the subtask's details, creating a log of the implementation journey that helps the AI (and human developers) learn, adapt, and avoid repeating errors.
+
+7. **Review & Update Rules (Post-Implementation):**
+ * Once the implementation for the subtask is functionally complete, review all code changes and the relevant chat history.
+ * Identify any new or modified code patterns, conventions, or best practices established during the implementation.
+ * Create new or update existing rules following internal guidelines (previously linked to `cursor_rules.md` and `self_improve.md`).
+
+8. **Mark Task Complete:**
+ * After verifying the implementation and updating any necessary rules, mark the subtask as completed: `set_task_status` / `task-master set-status --id= --status=done`.
+
+9. **Commit Changes (If using Git):**
+ * Stage the relevant code changes and any updated/new rule files (`git add .`).
+ * Craft a comprehensive Git commit message summarizing the work done for the subtask, including both code implementation and any rule adjustments.
+ * Execute the commit command directly in the terminal (e.g., `git commit -m 'feat(module): Implement feature X for subtask \n\n- Details about changes...\n- Updated rule Y for pattern Z'`).
+ * Consider if a Changeset is needed according to internal versioning guidelines (previously linked to `changeset.md`). If so, run `npm run changeset`, stage the generated file, and amend the commit or create a new one.
+
+10. **Proceed to Next Subtask:**
+ * Identify the next subtask (e.g., using `next_task` / `task-master next`).
+
+## Code Analysis & Refactoring Techniques
+
+- **Top-Level Function Search**:
+ - Useful for understanding module structure or planning refactors.
+ - Use grep/ripgrep to find exported functions/constants:
+ `rg "export (async function|function|const) \w+"` or similar patterns.
+ - Can help compare functions between files during migrations or identify potential naming conflicts.
+
+---
+*This workflow provides a general guideline. Adapt it based on your specific project needs and team practices.*
\ No newline at end of file
diff --git a/packages/.roo/rules/roo_rules.md b/packages/.roo/rules/roo_rules.md
new file mode 100644
index 0000000..cec3c64
--- /dev/null
+++ b/packages/.roo/rules/roo_rules.md
@@ -0,0 +1,53 @@
+---
+description: Guidelines for creating and maintaining Roo Code rules to ensure consistency and effectiveness.
+globs: .roo/rules/*.md
+alwaysApply: true
+---
+
+- **Required Rule Structure:**
+ ```markdown
+ ---
+ description: Clear, one-line description of what the rule enforces
+ globs: path/to/files/*.ext, other/path/**/*
+ alwaysApply: boolean
+ ---
+
+ - **Main Points in Bold**
+ - Sub-points with details
+ - Examples and explanations
+ ```
+
+- **File References:**
+ - Use `[filename](mdc:path/to/file)` ([filename](mdc:filename)) to reference files
+ - Example: [prisma.md](mdc:.roo/rules/prisma.md) for rule references
+ - Example: [schema.prisma](mdc:prisma/schema.prisma) for code references
+
+- **Code Examples:**
+ - Use language-specific code blocks
+ ```typescript
+ // ✅ DO: Show good examples
+ const goodExample = true;
+
+ // ❌ DON'T: Show anti-patterns
+ const badExample = false;
+ ```
+
+- **Rule Content Guidelines:**
+ - Start with high-level overview
+ - Include specific, actionable requirements
+ - Show examples of correct implementation
+ - Reference existing code when possible
+ - Keep rules DRY by referencing other rules
+
+- **Rule Maintenance:**
+ - Update rules when new patterns emerge
+ - Add examples from actual codebase
+ - Remove outdated patterns
+ - Cross-reference related rules
+
+- **Best Practices:**
+ - Use bullet points for clarity
+ - Keep descriptions concise
+ - Include both DO and DON'T examples
+ - Reference actual code over theoretical examples
+ - Use consistent formatting across rules
\ No newline at end of file
diff --git a/packages/.roo/rules/self_improve.md b/packages/.roo/rules/self_improve.md
new file mode 100644
index 0000000..e3af95e
--- /dev/null
+++ b/packages/.roo/rules/self_improve.md
@@ -0,0 +1,72 @@
+---
+description: Guidelines for continuously improving Roo Code rules based on emerging code patterns and best practices.
+globs: **/*
+alwaysApply: true
+---
+
+- **Rule Improvement Triggers:**
+ - New code patterns not covered by existing rules
+ - Repeated similar implementations across files
+ - Common error patterns that could be prevented
+ - New libraries or tools being used consistently
+ - Emerging best practices in the codebase
+
+- **Analysis Process:**
+ - Compare new code with existing rules
+ - Identify patterns that should be standardized
+ - Look for references to external documentation
+ - Check for consistent error handling patterns
+ - Monitor test patterns and coverage
+
+- **Rule Updates:**
+ - **Add New Rules When:**
+ - A new technology/pattern is used in 3+ files
+ - Common bugs could be prevented by a rule
+ - Code reviews repeatedly mention the same feedback
+ - New security or performance patterns emerge
+
+ - **Modify Existing Rules When:**
+ - Better examples exist in the codebase
+ - Additional edge cases are discovered
+ - Related rules have been updated
+ - Implementation details have changed
+
+- **Example Pattern Recognition:**
+ ```typescript
+ // If you see repeated patterns like:
+ const data = await prisma.user.findMany({
+ select: { id: true, email: true },
+ where: { status: 'ACTIVE' }
+ });
+
+ // Consider adding to [prisma.md](mdc:.roo/rules/prisma.md):
+ // - Standard select fields
+ // - Common where conditions
+ // - Performance optimization patterns
+ ```
+
+- **Rule Quality Checks:**
+ - Rules should be actionable and specific
+ - Examples should come from actual code
+ - References should be up to date
+ - Patterns should be consistently enforced
+
+- **Continuous Improvement:**
+ - Monitor code review comments
+ - Track common development questions
+ - Update rules after major refactors
+ - Add links to relevant documentation
+ - Cross-reference related rules
+
+- **Rule Deprecation:**
+ - Mark outdated patterns as deprecated
+ - Remove rules that no longer apply
+ - Update references to deprecated rules
+ - Document migration paths for old patterns
+
+- **Documentation Updates:**
+ - Keep examples synchronized with code
+ - Update references to external docs
+ - Maintain links between related rules
+ - Document breaking changes
+Follow [cursor_rules.md](mdc:.roo/rules/cursor_rules.md) for proper rule formatting and structure.
diff --git a/packages/.roo/rules/taskmaster.md b/packages/.roo/rules/taskmaster.md
new file mode 100644
index 0000000..1e64633
--- /dev/null
+++ b/packages/.roo/rules/taskmaster.md
@@ -0,0 +1,557 @@
+---
+description: Comprehensive reference for Taskmaster MCP tools and CLI commands.
+globs: **/*
+alwaysApply: true
+---
+# Taskmaster Tool & Command Reference
+
+This document provides a detailed reference for interacting with Taskmaster, covering both the recommended MCP tools, suitable for integrations like Roo Code, and the corresponding `task-master` CLI commands, designed for direct user interaction or fallback.
+
+**Note:** For interacting with Taskmaster programmatically or via integrated tools, using the **MCP tools is strongly recommended** due to better performance, structured data, and error handling. The CLI commands serve as a user-friendly alternative and fallback.
+
+**Important:** Several MCP tools involve AI processing... The AI-powered tools include `parse_prd`, `analyze_project_complexity`, `update_subtask`, `update_task`, `update`, `expand_all`, `expand_task`, and `add_task`.
+
+**🏷️ Tagged Task Lists System:** Task Master now supports **tagged task lists** for multi-context task management. This allows you to maintain separate, isolated lists of tasks for different features, branches, or experiments. Existing projects are seamlessly migrated to use a default "master" tag. Most commands now support a `--tag ` flag to specify which context to operate on. If omitted, commands use the currently active tag.
+
+---
+
+## Initialization & Setup
+
+### 1. Initialize Project (`init`)
+
+* **MCP Tool:** `initialize_project`
+* **CLI Command:** `task-master init [options]`
+* **Description:** `Set up the basic Taskmaster file structure and configuration in the current directory for a new project.`
+* **Key CLI Options:**
+ * `--name `: `Set the name for your project in Taskmaster's configuration.`
+ * `--description `: `Provide a brief description for your project.`
+ * `--version `: `Set the initial version for your project, e.g., '0.1.0'.`
+ * `-y, --yes`: `Initialize Taskmaster quickly using default settings without interactive prompts.`
+* **Usage:** Run this once at the beginning of a new project.
+* **MCP Variant Description:** `Set up the basic Taskmaster file structure and configuration in the current directory for a new project by running the 'task-master init' command.`
+* **Key MCP Parameters/Options:**
+ * `projectName`: `Set the name for your project.` (CLI: `--name `)
+ * `projectDescription`: `Provide a brief description for your project.` (CLI: `--description `)
+ * `projectVersion`: `Set the initial version for your project, e.g., '0.1.0'.` (CLI: `--version `)
+ * `authorName`: `Author name.` (CLI: `--author `)
+ * `skipInstall`: `Skip installing dependencies. Default is false.` (CLI: `--skip-install`)
+ * `addAliases`: `Add shell aliases tm and taskmaster. Default is false.` (CLI: `--aliases`)
+ * `yes`: `Skip prompts and use defaults/provided arguments. Default is false.` (CLI: `-y, --yes`)
+* **Usage:** Run this once at the beginning of a new project, typically via an integrated tool like Roo Code. Operates on the current working directory of the MCP server.
+* **Important:** Once complete, you *MUST* parse a prd in order to generate tasks. There will be no tasks files until then. The next step after initializing should be to create a PRD using the example PRD in .taskmaster/templates/example_prd.txt.
+* **Tagging:** Use the `--tag` option to parse the PRD into a specific, non-default tag context. If the tag doesn't exist, it will be created automatically. Example: `task-master parse-prd spec.txt --tag=new-feature`.
+
+### 2. Parse PRD (`parse_prd`)
+
+* **MCP Tool:** `parse_prd`
+* **CLI Command:** `task-master parse-prd [file] [options]`
+* **Description:** `Parse a Product Requirements Document, PRD, or text file with Taskmaster to automatically generate an initial set of tasks in tasks.json.`
+* **Key Parameters/Options:**
+ * `input`: `Path to your PRD or requirements text file that Taskmaster should parse for tasks.` (CLI: `[file]` positional or `-i, --input `)
+ * `output`: `Specify where Taskmaster should save the generated 'tasks.json' file. Defaults to '.taskmaster/tasks/tasks.json'.` (CLI: `-o, --output `)
+ * `numTasks`: `Approximate number of top-level tasks Taskmaster should aim to generate from the document.` (CLI: `-n, --num-tasks `)
+ * `force`: `Use this to allow Taskmaster to overwrite an existing 'tasks.json' without asking for confirmation.` (CLI: `-f, --force`)
+* **Usage:** Useful for bootstrapping a project from an existing requirements document.
+* **Notes:** Task Master will strictly adhere to any specific requirements mentioned in the PRD, such as libraries, database schemas, frameworks, tech stacks, etc., while filling in any gaps where the PRD isn't fully specified. Tasks are designed to provide the most direct implementation path while avoiding over-engineering.
+* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. If the user does not have a PRD, suggest discussing their idea and then use the example PRD in `.taskmaster/templates/example_prd.txt` as a template for creating the PRD based on their idea, for use with `parse-prd`.
+
+---
+
+## AI Model Configuration
+
+### 2. Manage Models (`models`)
+* **MCP Tool:** `models`
+* **CLI Command:** `task-master models [options]`
+* **Description:** `View the current AI model configuration or set specific models for different roles (main, research, fallback). Allows setting custom model IDs for Ollama and OpenRouter.`
+* **Key MCP Parameters/Options:**
+ * `setMain `: `Set the primary model ID for task generation/updates.` (CLI: `--set-main `)
+ * `setResearch `: `Set the model ID for research-backed operations.` (CLI: `--set-research `)
+ * `setFallback `: `Set the model ID to use if the primary fails.` (CLI: `--set-fallback `)
+ * `ollama `: `Indicates the set model ID is a custom Ollama model.` (CLI: `--ollama`)
+ * `openrouter `: `Indicates the set model ID is a custom OpenRouter model.` (CLI: `--openrouter`)
+ * `listAvailableModels `: `If true, lists available models not currently assigned to a role.` (CLI: No direct equivalent; CLI lists available automatically)
+ * `projectRoot `: `Optional. Absolute path to the project root directory.` (CLI: Determined automatically)
+* **Key CLI Options:**
+ * `--set-main `: `Set the primary model.`
+ * `--set-research `: `Set the research model.`
+ * `--set-fallback `: `Set the fallback model.`
+ * `--ollama`: `Specify that the provided model ID is for Ollama (use with --set-*).`
+ * `--openrouter`: `Specify that the provided model ID is for OpenRouter (use with --set-*). Validates against OpenRouter API.`
+ * `--bedrock`: `Specify that the provided model ID is for AWS Bedrock (use with --set-*).`
+ * `--setup`: `Run interactive setup to configure models, including custom Ollama/OpenRouter IDs.`
+* **Usage (MCP):** Call without set flags to get current config. Use `setMain`, `setResearch`, or `setFallback` with a valid model ID to update the configuration. Use `listAvailableModels: true` to get a list of unassigned models. To set a custom model, provide the model ID and set `ollama: true` or `openrouter: true`.
+* **Usage (CLI):** Run without flags to view current configuration and available models. Use set flags to update specific roles. Use `--setup` for guided configuration, including custom models. To set a custom model via flags, use `--set-=