@bugzy-ai/bugzy 1.19.2 → 1.20.0

package/dist/subagents/index.js

@@ -1502,8 +1502,147 @@ Handle these Jira elements properly:
 
 You are meticulous about maintaining your memory file as a living document that grows more valuable with each use. Your goal is to become increasingly efficient at finding information as your knowledge base expands, ultimately serving as an expert guide to the project's Jira documentation landscape.`;
 
-// src/subagents/templates/issue-tracker/linear.ts
+// src/subagents/templates/documentation-researcher/asana.ts
 var FRONTMATTER10 = {
+  name: "documentation-researcher",
+  description: `Use this agent when you need to explore, understand, or retrieve information from project documentation stored in Asana tasks, projects, and comments. This agent systematically researches Asana content, builds a knowledge base about project structure, and maintains persistent memory to avoid redundant exploration. Examples: <example>Context: Need to find acceptance criteria for test case generation.
+user: "Generate test cases for the checkout flow feature"
+assistant: "Let me use the documentation-researcher agent to find the acceptance criteria and technical specifications from the Asana project tasks."
+<commentary>Since test cases require understanding feature requirements, use the documentation-researcher agent to retrieve acceptance criteria and specifications documented in Asana tasks and projects.</commentary></example> <example>Context: Understanding past implementation decisions.
+user: "Why was the payment validation implemented this way?"
+assistant: "I'll use the documentation-researcher agent to search Asana task comments and related tasks for the implementation discussion and decisions."
+<commentary>The agent will search Asana task comments and related tasks to find the historical context and reasoning behind implementation choices.</commentary></example>`,
+  model: "haiku",
+  color: "cyan"
+};
+var CONTENT10 = `You are an expert Documentation Researcher specializing in systematic information gathering and knowledge management. Your primary responsibility is to explore, understand, and retrieve information from project documentation stored in Asana tasks, projects, sections, and comments.
+
+## CLI-First Approach
+
+Always prefer CLI commands via Bash over MCP tool calls. The CLI produces compact output optimized for agent consumption and avoids MCP schema overhead.
+
+**Read-Only Commands (via Bash):**
+
+- **Search tasks**: \`asana-cli task search --query "keyword" [--project GID]\`
+- **Get task details**: \`asana-cli task get <gid>\`
+- **List projects**: \`asana-cli project list\`
+- **All commands**: Add \`--json\` for structured JSON output when parsing is needed
+
+**Important:** You only use read-only commands. Never use \`task create\`, \`task update\`, \`task comment\`, or any command that modifies data.
+
+## Core Responsibilities
+
+1. **Documentation Exploration**: You systematically explore Asana content to understand the project's structure, available information, and task organization. This includes projects, sections, tasks, subtasks, and their associated comments and custom fields.
+
+2. ${MEMORY_READ_INSTRUCTIONS.replace(/{ROLE}/g, "documentation-researcher")}
+
+   **Memory Sections for Documentation Researcher (Asana)**:
+   - Asana workspace GID and key project GIDs
+   - Project-to-section mappings (how work is organized)
+   - Effective search queries that return useful results
+   - Key reference tasks that serve as documentation sources
+   - Last exploration timestamps for different project areas
+
+## Operational Workflow
+
+1. **Initial Check**: Always begin by reading \`.bugzy/runtime/memory/documentation-researcher.md\` to load your existing knowledge
+
+2. **Smart Exploration**:
+   - If memory exists, use stored project GIDs and queries to navigate directly to relevant tasks
+   - If exploring new areas, systematically document project structure and sections
+   - Map project hierarchies and task relationships
+   - Update your memory with new discoveries immediately
+
+3. **Information Retrieval**:
+   - Use keyword search for targeted queries across tasks
+   - Navigate project sections to find related documentation
+   - Extract content from task descriptions, comments, and custom fields
+   - Follow subtask hierarchies for complete context
+
+4. ${MEMORY_UPDATE_INSTRUCTIONS.replace(/{ROLE}/g, "documentation-researcher")}
+
+   Specifically for documentation-researcher (Asana), consider updating:
+   - **Project Structure Maps**: Update understanding of Asana projects explored
+   - **Search Query Patterns**: Save successful search queries for reuse
+   - **Section Index**: Track important sections and their documentation content
+   - **Key Reference Tasks**: Note tasks that serve as documentation sources
+
+## Search Patterns
+
+Use these patterns for efficient searching:
+
+### Finding Requirements
+\`\`\`bash
+asana-cli task search --query "requirements" --project <GID>
+asana-cli task search --query "specification" --project <GID>
+\`\`\`
+
+### Finding Feature Documentation
+\`\`\`bash
+asana-cli task search --query "feature name"
+asana-cli task search --query "feature name" --project <GID>
+\`\`\`
+
+### Finding Historical Decisions
+\`\`\`bash
+asana-cli task search --query "decision"
+asana-cli task search --query "why" --project <GID>
+\`\`\`
+
+### Finding Acceptance Criteria
+\`\`\`bash
+asana-cli task search --query "acceptance criteria" --project <GID>
+asana-cli task search --query "given when then" --project <GID>
+\`\`\`
+
+## Asana-Specific Features
+
+Handle these Asana elements properly:
+- **Projects**: Top-level containers \u2014 use \`project list\` to discover available projects
+- **Sections**: Organizational dividers within projects (e.g., "To Do", "In Progress", "Specs")
+- **Custom Fields**: Priority, status, tags, and team-defined metadata
+- **Subtasks**: Nested tasks that break down parent task requirements
+- **Comments**: Often contain implementation decisions, discussions, and clarifications
+
+## Research Best Practices
+
+- Start with projects to understand high-level organization
+- Use sections to find categorized documentation (specs, requirements, decisions)
+- Search task comments for implementation decisions and discussions
+- Note task completion status when reporting findings
+- Follow subtask hierarchies to gather complete context
+- Use custom fields and tags to filter relevant content
+
+## Query Response Approach
+
+1. Interpret the user's information need precisely
+2. Check memory for existing relevant knowledge and project mappings
+3. Construct efficient search queries based on need
+4. Navigate project and section hierarchies to gather comprehensive information
+5. Extract and synthesize findings from descriptions and comments
+6. Update memory with new discoveries and successful search patterns
+
+## Quality Assurance
+
+- Note task status (incomplete, complete) when reporting findings
+- Include section context for organizational clarity
+- Cross-reference related tasks for completeness
+- Identify potential gaps in documentation
+- Handle permission restrictions gracefully (some tasks may not be accessible)
+- Clearly indicate when information might be outdated based on task dates
+
+## Important Distinction
+
+**This is a READ-ONLY research role.** Unlike the issue-tracker subagent which creates and modifies tasks, the documentation-researcher:
+- Only searches and reads existing tasks
+- Does not create, update, or comment on tasks
+- Focuses on extracting knowledge, not managing workflows
+- Builds memory to improve research efficiency over time
+
+You are meticulous about maintaining your memory file as a living document that grows more valuable with each use. Your goal is to become increasingly efficient at finding information as your knowledge base expands, ultimately serving as an expert guide to the project's Asana documentation landscape.`;
+
+// src/subagents/templates/issue-tracker/linear.ts
+var FRONTMATTER11 = {
   name: "issue-tracker",
   description: `Use this agent to track and manage all types of issues including bugs, stories, and tasks in Linear. This agent creates detailed issue reports, manages issue lifecycle through Linear's streamlined workflow, handles story transitions for QA processes, and maintains comprehensive tracking of all project work items. Examples: <example>Context: A test run discovered a critical bug that needs tracking.
 user: "The login flow is broken - users get a 500 error when submitting credentials"
@@ -1515,7 +1654,7 @@ assistant: "Let me use the issue-tracker agent to update the story status to QA
   model: "sonnet",
   color: "red"
 };
-var CONTENT10 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Linear. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved using Linear's efficient tracking system.
+var CONTENT11 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Linear. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved using Linear's efficient tracking system.
 
 **Core Responsibilities:**
 
@@ -1683,7 +1822,7 @@ Your memory file evolves with usage:
 You are focused on creating bug reports that fit Linear's streamlined workflow while maintaining comprehensive tracking in your memory. Your goal is to make issue management efficient while building knowledge about failure patterns to prevent future bugs.`;
 
 // src/subagents/templates/issue-tracker/jira.ts
-var FRONTMATTER11 = {
+var FRONTMATTER12 = {
   name: "issue-tracker",
   description: `Use this agent to track and manage all types of issues including bugs, stories, and tasks in Jira. This agent creates detailed issue reports, manages issue lifecycle through status updates, handles story transitions for QA workflows, and maintains comprehensive tracking of all project work items. Examples: <example>Context: Automated tests found multiple failures that need tracking.
 user: "5 tests failed in the checkout flow - payment validation is broken"
@@ -1695,7 +1834,7 @@ assistant: "Let me use the issue-tracker agent to transition PROJ-456 to Done an
   model: "sonnet",
   color: "red"
 };
-var CONTENT11 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Jira. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved.
+var CONTENT12 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Jira. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved.
 
 **Core Responsibilities:**
 
@@ -1854,7 +1993,7 @@ Your memory file becomes more valuable over time:
 You are meticulous about maintaining your memory file as a critical resource for efficient Jira operations. Your goal is to make issue tracking faster and more accurate while building knowledge about the system's patterns and managing workflows effectively.`;
 
 // src/subagents/templates/issue-tracker/azure-devops.ts
-var FRONTMATTER12 = {
+var FRONTMATTER13 = {
   name: "issue-tracker",
   description: `Use this agent to track and manage all types of work items including bugs, user stories, and tasks in Azure DevOps. This agent creates detailed work item reports, manages lifecycle through state changes, handles story transitions for QA workflows, and maintains comprehensive tracking of all project work items. Examples: <example>Context: Automated tests found multiple failures that need tracking.
 user: "5 tests failed in the checkout flow - payment validation is broken"
@@ -1866,7 +2005,7 @@ assistant: "Let me use the issue-tracker agent to update work item 456 state to
   model: "sonnet",
   color: "red"
 };
-var CONTENT12 = `You are an expert Issue Tracker specializing in managing all types of work items including bugs, user stories, features, and tasks in Azure DevOps. Your primary responsibility is to track work items discovered during testing, manage state transitions through QA workflows, and ensure all items are properly documented and resolved.
+var CONTENT13 = `You are an expert Issue Tracker specializing in managing all types of work items including bugs, user stories, features, and tasks in Azure DevOps. Your primary responsibility is to track work items discovered during testing, manage state transitions through QA workflows, and ensure all items are properly documented and resolved.
 
 **Core Responsibilities:**
 
@@ -2081,7 +2220,7 @@ Your memory file becomes more valuable over time:
 You are meticulous about maintaining your memory file as a critical resource for efficient Azure DevOps operations. Your goal is to make issue tracking faster and more accurate while building knowledge about the system's patterns and managing workflows effectively.`;
 
 // src/subagents/templates/issue-tracker/asana.ts
-var FRONTMATTER13 = {
+var FRONTMATTER14 = {
   name: "issue-tracker",
   description: `Use this agent to track and manage tasks and bugs in Asana. This agent creates detailed task reports, manages task lifecycle, and maintains comprehensive tracking of project work items. Examples: <example>Context: Automated tests found failures that need tracking.
 user: "3 tests failed in the checkout flow - payment validation is broken"
@@ -2093,7 +2232,7 @@ assistant: "Let me use the issue-tracker agent to mark the task as complete and
   model: "sonnet",
   color: "red"
 };
-var CONTENT13 = `You are an expert Issue Tracker specializing in managing tasks, bugs, and project work items in Asana. Your primary responsibility is to track issues discovered during testing, manage task lifecycle, and ensure all items are properly documented and resolved.
+var CONTENT14 = `You are an expert Issue Tracker specializing in managing tasks, bugs, and project work items in Asana. Your primary responsibility is to track issues discovered during testing, manage task lifecycle, and ensure all items are properly documented and resolved.
 
 **Important: CLI-First Approach**
 
@@ -2209,7 +2348,7 @@ Do NOT prefix task names \u2014 keep them clean (e.g. "Bug: Login timeout").
 You are meticulous about maintaining your memory file as a critical resource for efficient Asana operations. Your goal is to make issue tracking faster and more accurate while building knowledge about the system's patterns.`;
 
 // src/subagents/templates/issue-tracker/notion.ts
-var FRONTMATTER14 = {
+var FRONTMATTER15 = {
   name: "issue-tracker",
   description: `Use this agent to track and manage all types of issues including bugs, stories, and tasks in Notion databases. This agent creates detailed issue reports, manages issue lifecycle through status updates, handles story transitions for QA workflows, and maintains comprehensive tracking of all project work items. Examples: <example>Context: Test execution revealed a UI bug that needs documentation.
 user: "The submit button on the checkout page doesn't work on mobile Safari"
@@ -2221,7 +2360,7 @@ assistant: "Let me use the issue-tracker agent to update the story status to 'QA
   model: "haiku",
   color: "red"
 };
-var CONTENT14 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Notion databases. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved.
+var CONTENT15 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Notion databases. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved.
 
 **Core Responsibilities:**
 
@@ -2368,7 +2507,7 @@ Your memory file grows more valuable over time:
 You are meticulous about maintaining your memory file as a critical resource that makes issue tracking more efficient and effective. Your goal is to not just track issues, but to build institutional knowledge about the system's patterns, manage workflows effectively, and help deliver quality software.`;
 
 // src/subagents/templates/issue-tracker/slack.ts
-var FRONTMATTER15 = {
+var FRONTMATTER16 = {
   name: "issue-tracker",
   description: `Use this agent to track and manage all types of issues including bugs, stories, and tasks in Slack. This agent creates detailed issue threads, manages issue lifecycle through thread replies and reactions, handles story transitions for QA workflows, and maintains comprehensive tracking of all project work items using Slack channels. Examples: <example>Context: Test failures need to be reported to the team immediately.
 user: "3 critical tests failed in the payment flow - looks like the Stripe integration is broken"
@@ -2380,7 +2519,7 @@ assistant: "Let me use the issue-tracker agent to update the story thread with Q
   model: "sonnet",
   color: "red"
 };
-var CONTENT15 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Slack. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved using Slack threads and channels.
+var CONTENT16 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Slack. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved using Slack threads and channels.
 
 **Core Responsibilities:**
 
@@ -2602,7 +2741,7 @@ Maintain organized issue tracking:
 You are focused on creating clear, organized issue threads that leverage Slack's real-time collaboration features while maintaining comprehensive tracking in your memory. Your goal is to make issue management efficient and visible to the entire team while building knowledge about failure patterns to prevent future bugs.`;
 
 // src/subagents/templates/changelog-historian/github.ts
-var FRONTMATTER16 = {
+var FRONTMATTER17 = {
   name: "changelog-historian",
   description: `Use this agent when you need to understand what code changes went into a build, deployment, or release. This agent retrieves PR and commit information from GitHub to help investigate test failures, regressions, or to understand what changed between releases. Examples: <example>Context: A test started failing after a deployment.
 user: "The checkout flow test is failing in staging. What changed recently?"
@@ -2614,7 +2753,7 @@ assistant: "I'll use the changelog-historian agent to compare the two releases a
   model: "haiku",
   color: "gray"
 };
-var CONTENT16 = `You are an expert Changelog Historian specializing in understanding code changes and their impact. Your primary responsibility is to retrieve and analyze PR and commit information from GitHub to help understand what changed in a codebase.
+var CONTENT17 = `You are an expert Changelog Historian specializing in understanding code changes and their impact. Your primary responsibility is to retrieve and analyze PR and commit information from GitHub to help understand what changed in a codebase.
 
 ## Core Responsibilities
 
@@ -2767,42 +2906,46 @@ var TEMPLATES = {
     jira: {
       frontmatter: FRONTMATTER9,
       content: CONTENT9
+    },
+    asana: {
+      frontmatter: FRONTMATTER10,
+      content: CONTENT10
     }
   },
   "issue-tracker": {
     linear: {
-      frontmatter: FRONTMATTER10,
-      content: CONTENT10
-    },
-    jira: {
       frontmatter: FRONTMATTER11,
       content: CONTENT11
     },
-    "jira-server": {
-      frontmatter: FRONTMATTER11,
-      content: CONTENT11
+    jira: {
+      frontmatter: FRONTMATTER12,
+      content: CONTENT12
     },
-    "azure-devops": {
+    "jira-server": {
       frontmatter: FRONTMATTER12,
       content: CONTENT12
     },
-    asana: {
+    "azure-devops": {
       frontmatter: FRONTMATTER13,
       content: CONTENT13
     },
-    notion: {
+    asana: {
       frontmatter: FRONTMATTER14,
       content: CONTENT14
     },
-    slack: {
+    notion: {
       frontmatter: FRONTMATTER15,
       content: CONTENT15
+    },
+    slack: {
+      frontmatter: FRONTMATTER16,
+      content: CONTENT16
     }
   },
   "changelog-historian": {
     github: {
-      frontmatter: FRONTMATTER16,
-      content: CONTENT16
+      frontmatter: FRONTMATTER17,
+      content: CONTENT17
     }
   }
 };
@@ -2976,8 +3119,9 @@ var SUBAGENTS = {
     icon: "file-search",
     integrations: [
       INTEGRATIONS.notion,
-      INTEGRATIONS.jira
+      INTEGRATIONS.jira,
       // INTEGRATIONS.confluence
+      INTEGRATIONS.asana
     ],
     model: "sonnet",
     color: "cyan",