dmtools v1.7.255B

Immutable. This exact content is served forever at /api/v1/blob/0c57b6de5252e004.

---
name: dmtools
description: Comprehensive documentation and assistance for DMTools - an enterprise dark-factory orchestrator with 334+ MCP tools for Jira, Azure DevOps, GitHub, GitLab, Figma, Confluence, Teams, and test automation. Use when working with DMTools, configuring integrations, developing JavaScript agents, generating test cases, building reports (ReportGenerator/ReportVisualizer), creating CLI agent workflows (Teammate/CliAgent), or setting up CI/CD run tracing (ciRunUrl) for Teammate/Expert/TestCasesGenerator/CliAgent jobs.
license: Apache-2.0
compatibility:
  - Java 17+
  - macOS, Linux, Windows (WSL)
metadata:
  version: 1.7.255
  author: DMtools Team
  repository: https://github.com/epam/dm.ai
  documentation: https://github.com/epam/dm.ai/tree/main/dmtools-ai-docs
---

# DMtools Development Assistant

DMTools is an enterprise dark-factory orchestrator that integrates with multiple platforms and provides 334+ MCP tools for reusable delivery automation.

## 🔧 FIRST-TIME SETUP (DO THIS PROACTIVELY)

**When a user mentions DMtools or asks to use it, IMMEDIATELY perform these checks:**

### 🚀 Quick Installation Bootstrap (Recommended)

Install or refresh DMtools from the latest release first, then continue with the configuration checks below:

```bash
# Install or update DMtools from the latest release
curl -fsSL https://github.com/epam/dm.ai/releases/latest/download/install.sh | bash
```

**Then make sure to:**
1. ✓ Check whether `dmtools` is available
2. ✓ Create `dmtools.env` if missing
3. ✓ Add DMtools files to `.gitignore`
4. ✓ Verify Java installation
5. ✓ Test DMtools functionality with `dmtools list`

**OR follow manual steps below:**

**Focused skill packages:** install only the integrations you need with `DMTOOLS_SKILLS=jira,github` and the skill installer described in [references/installation/README.md#install-only-the-skills-you-need](references/installation/README.md#install-only-the-skills-you-need).

**Child agent configs:** define a shared base config and extend it with the existing [`parent` inheritance pattern](references/configuration/json-config-rules.md#config-inheritance-via-parent).

### Step 1: Check if DMtools is installed
```bash
# Check if dmtools command is available
which dmtools || echo "DMtools not installed"
```

**If NOT installed:**
```bash
# Offer to install DMtools automatically
curl -fsSL https://github.com/epam/dm.ai/releases/latest/download/install.sh | bash
```

### Step 2: Check for dmtools.env configuration
```bash
# Check if dmtools.env exists in current directory or home
ls dmtools.env ~/.dmtools.env 2>/dev/null || echo "No dmtools.env found"
```

**If NOT found, help user create it:**

1. **Ask user which integrations they need** (Jira, ADO, Figma, etc.)
2. **Ask user which AI provider they want** (Gemini free tier recommended)
3. **Create dmtools.env with appropriate template** (see Configuration Template below)
4. **Add dmtools.env to .gitignore** (contains secrets!)

### Step 3: Verify .gitignore
```bash
# Check if dmtools files are in .gitignore
grep -q "dmtools.env\|dmtools-local.env" .gitignore 2>/dev/null || echo "Not in .gitignore"
```

**If NOT in .gitignore, add these lines:**
```gitignore
# DMtools configuration (contains secrets)
dmtools.env
dmtools-local.env
```

### Configuration Template

When creating dmtools.env, use this template and fill with user's credentials:

```bash
# dmtools.env - NEVER commit this file
# Generated by DMtools skill assistant

# ================================
# INTEGRATIONS (choose what you need)
# ================================

# Jira (if user needs Jira)
JIRA_BASE_PATH=https://your-company.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-jira-api-token
JIRA_AUTH_TYPE=Basic

# Azure DevOps (if user needs ADO)
# ADO_BASE_PATH=https://dev.azure.com/your-org
# ADO_PAT_TOKEN=your-ado-pat-token

# ================================
# AI PROVIDER (required - choose one)
# ================================

# Gemini (RECOMMENDED - free tier available)
GEMINI_API_KEY=your-gemini-api-key
# Get free key: https://aistudio.google.com/app/apikey

# OR OpenAI
# OPENAI_API_KEY=your-openai-api-key

# OR AWS Bedrock
# BEDROCK_ACCESS_KEY_ID=your-aws-key
# BEDROCK_SECRET_ACCESS_KEY=your-aws-secret

# ================================
# DEFAULTS
# ================================
DEFAULT_LLM=gemini
DEFAULT_TRACKER=jira
```

**Quick Links for API Tokens:**
- Jira: https://id.atlassian.com/manage-profile/security/api-tokens
- Gemini: https://aistudio.google.com/app/apikey (FREE - 15 req/min)
- OpenAI: https://platform.openai.com/api-keys
- ADO: https://dev.azure.com → User Settings → Personal Access Tokens

### Step 4: Test Installation
```bash
# Verify installation works
dmtools list | head -5
```

## When to Use

Use this skill when:
- Installing or configuring DMtools (do setup steps above first!)
- Setting up integrations (Jira, Azure DevOps, Figma, Confluence, Teams)
- Configuring AI providers (Gemini, OpenAI, Claude, DIAL, Ollama)
- Developing JavaScript agents with MCP tools
- Generating test cases (Jira, Xray, Cucumber)
- Generating analytics reports (ReportGenerator, ReportVisualizer)
- Troubleshooting DMtools issues
- Working with dmtools.env configuration
- Creating AI teammate configurations (Teammate/CliAgent)
- Setting up CI/CD run tracing (`ciRunUrl`) for ticket traceability

## Quick Reference

**⚠️ IMPORTANT**: If this is first time using DMtools, see [FIRST-TIME SETUP](#-first-time-setup-do-this-proactively) section above.

### Manual Installation Steps

If automated setup didn't work, follow these manual steps:

#### 1. Install DMtools CLI
```bash
curl -fsSL https://github.com/epam/dm.ai/releases/latest/download/install.sh | bash
```

#### 2. Create dmtools.env
Create `dmtools.env` in project root (see template in FIRST-TIME SETUP section)

#### 3. Add to .gitignore
```bash
echo -e "\n# DMtools configuration\ndmtools.env\ndmtools-local.env" >> .gitignore
```

#### 4. Get API Tokens
- Jira: https://id.atlassian.com/manage-profile/security/api-tokens
- Gemini (FREE): https://aistudio.google.com/app/apikey
- OpenAI: https://platform.openai.com/api-keys

See [Installation Guide](references/installation/README.md#️-configuration-setup) for detailed setup.

### Common Commands
```bash
dmtools list                          # List all 334+ MCP tools
dmtools jira_get_ticket PROJ-123      # Get Jira ticket
dmtools run agents/config.json        # Run configuration
dmtools run agents/config.json --ciRunUrl "https://ci.example.com/runs/42"  # With CI tracing
dmtools run agents/config.json "${ENCODED_CONFIG}" --inputJql "key=PROJ-1"  # With overrides
```

## Core Capabilities

### 334+ MCP Tools Available

**Complete Reference**: [references/mcp-tools/README.md](references/mcp-tools/README.md) - Auto-generated from actual DMtools build

Current breakdown (20 integrations):
- **Jira** (58 tools): Ticket management, search, comments, fields
- **Jira Xray** (11 tools): Xray test management
- **Teams** (28 tools): Messages, chats, files, transcripts, meetings
- **Teams Auth** (3 tools): Teams authentication flows
- **Confluence** (24 tools): Page management, search, content access, attachments, inline comments
- **ADO** (38 tools): Azure DevOps work items, queries, comments, attachments, pull requests, code review threads
- **GitHub** (38 tools): Pull requests, issues, comments, workflows
- **GitLab** (30 tools): Merge requests, issues, CI/CD pipelines
- **Bitbucket** (1 tool): Pull request operations
- **Figma** (22 tools): Design extraction, icons, layers, styles, components
- **AI Providers** (15 tools): Chat, vision, and file inputs across Gemini, OpenAI, Anthropic, Bedrock, DIAL, Ollama, and Vertex
- **Knowledge Base** (5 tools): Document search, indexing, RAG
- **File** (4 tools): File operations, read/write
- **Mermaid** (3 tools): Diagram generation
- **SharePoint** (2 tools): Document management
- **Bitrise** (24 tools): Mobile CI/CD builds and artifacts
- **Jenkins** (7 tools): CI/CD job and build information
- **TestRail** (16 tools): Test case and test run management
- **Rally** (1 tool): Work item lookups
- **CLI** (1 tool): Command execution

**Example tools**:
- `jira_get_ticket`, `jira_search_by_jql`, `jira_xray_create_test`
- `ado_get_work_item`, `ado_move_to_state`, `ado_add_comment`
- `ado_list_prs`, `ado_get_pr`, `ado_add_pr_comment`, `ado_resolve_pr_thread`, `ado_merge_pr`
- `figma_get_layers`, `figma_get_icons`, `figma_download_node_image`
- `teams_send_message`, `teams_messages_since`, `teams_download_file`
- `gemini_ai_chat`, `openai_ai_chat`, `openai_ai_chat_with_files`, `bedrock_ai_chat`

### JavaScript Agent Pattern

All MCP tools are directly accessible as JavaScript functions in agents:

```javascript
function action(params) {
    try {
        // Direct MCP tool access
        const ticket = jira_get_ticket(params.ticketKey);
        const analysis = gemini_ai_chat(`Analyze: ${ticket.fields.description}`);

        // Process and return
        return { success: true, result: analysis };
    } catch (error) {
        return { success: false, error: error.toString() };
    }
}
```

## 📚 Detailed Documentation

| Category | Document | Description |
|----------|----------|-------------|
| **Installation** | [Installation Guide](references/installation/README.md) | Complete setup for all platforms (macOS, Linux, Windows) |
| | [Troubleshooting](references/installation/troubleshooting.md) | Common issues and solutions |
| **Configuration** | [Configuration Overview](references/configuration/README.md) | Environment variables and hierarchy |
| | [CLI Output Formats](references/configuration/cli-output-formats.md) | `json` / `toon` / `mini` — token savings up to 70% |
| | [JSON Configuration Rules](references/configuration/json-config-rules.md) | **⚠️ CRITICAL**: Rules for job configurations |
| | [Jira Setup](references/configuration/integrations/jira.md) | API tokens and 58 tools |
| | [Azure DevOps](references/configuration/integrations/ado.md) | PAT setup and 38+ tools |
| | [Gemini AI](references/configuration/ai-providers/gemini.md) | Free tier configuration (15 req/min) |
| | [Other AI Providers](references/configuration/ai-providers/) | OpenAI, Claude, DIAL, Ollama |
| **Jobs** | [Jobs Reference](references/jobs/README.md) | Complete guide to all 23 jobs |
| | [Teammate](references/jobs/README.md#teammate) | Flexible AI assistant with custom instructions |
| | [CliAgent](references/jobs/README.md#cliagent) | Lightweight CLI-agent orchestration without a tracker ticket |
| | [Expert](references/jobs/README.md#expert) | Domain expert Q&A based on project context |
| | [TestCasesGenerator](references/jobs/README.md#testcasesgenerator) | Automated test case generation |
| | [InstructionsGenerator](references/jobs/README.md#instructionsgenerator) | Build reusable implementation instructions from tracker tickets |
| | [JSRunner](references/jobs/README.md#jsrunner) | Execute a standalone JavaScript agent with DMtools context |
| | [DevProductivityReport](references/jobs/README.md#devproductivityreport) | Developer productivity metrics from tracker and SCM data |
| | [BAProductivityReport](references/jobs/README.md#baproductivityreport) | BA productivity metrics across created work and status changes |
| | [QAProductivityReport](references/jobs/README.md#qaproductivityreport) | QA productivity metrics across bugs, tests, and comments |
| | [ReportGenerator](references/reporting/report-generation.md) | Generate JSON and HTML analytics reports from configurable sources |
| | [ReportVisualizer](references/jobs/README.md#reportvisualizer) | Render an existing report JSON as interactive HTML |
| | [KBProcessingJob](references/jobs/README.md#kbprocessingjob) | Process source material into knowledge-base artifacts |
| **Agents** | [Agent Best Practices](references/agents/best-practices.md) | **⚠️ CRITICAL**: Patterns and lessons learned |
| | [JavaScript Agents](references/agents/javascript-agents.md) | GraalJS development with 334+ MCP tools |
| | [Teammate Configs](references/agents/teammate-configs.md) | JSON-based AI workflows (CLI safety v1.7.133+) |
| | [CLI Integration](references/agents/cli-integration.md) | Cursor, Claude, Copilot, Gemini CLI agents |
| **Testing** | [Test Generation](references/test-generation/xray-manual.md) | Xray test case creation |
| **MCP Tools** | [MCP Tools Reference](references/mcp-tools/README.md) | Auto-generated list of 334+ tools (20 integrations) |
| **CI/CD** | [GitHub Actions](references/workflows/github-actions-teammate.md) | Automated ticket processing + CI run tracing |

## ⚠️ CRITICAL: JSON Configuration "name" Field

**Before using any job configuration, understand this:**
 
The `"name"` field in JSON configs is **NOT** a user-defined name. It is a **Java class name** (technical identifier).

```json
{
  "name": "TestCasesGenerator"  // ← Exact Java class name (immutable)
}
```

- ✅ **DO**: Use exact name from docs: `TestCasesGenerator`, `Teammate`, `Expert`
- ❌ **DON'T**: Change it to "My Test Generator" or "test-generator"

**Why?** DMtools maps this name directly to Java code: `"TestCasesGenerator"` → `new TestCasesGenerator()`

See [JSON Configuration Rules](references/configuration/json-config-rules.md) for details.

---

## Common Tasks

### Configure Jira Integration
```bash
# 1. Generate API token at https://id.atlassian.com/manage-profile/security/api-tokens
# 2. Encode credentials
echo -n "email@company.com:token" | base64
# 3. Add to dmtools.env
JIRA_BASE_PATH=https://company.atlassian.net
JIRA_LOGIN_PASS_TOKEN=base64_output_here
```

### Generate Test Cases

**IMPORTANT**: `"name"` must exactly match Job class name. See [JSON Configuration Rules](references/configuration/json-config-rules.md).

```json
{
  "name": "TestCasesGenerator",
  "params": {
    "inputJql": "project = PROJ AND type = Story",
    "testCasesPriorities": "High, Medium, Low",
    "outputType": "creation",
    "testCaseIssueType": "Test",
    "existingTestCasesJql": "project = PROJ AND type = Test",
    "isFindRelated": true,
    "isGenerateNew": true
  }
}
```

### Create JavaScript Agent
```javascript
// agents/js/processTickets.js
function action(params) {
    const tickets = jira_search_by_jql(params.jql);

    for (const ticket of tickets) {
        // Process with AI
        const result = gemini_ai_chat(`Analyze: ${ticket.fields.summary}`);

        // Update ticket
        jira_post_comment(ticket.key, result);
    }

    return { processed: tickets.length };
}
```

### CI Run Tracing (GitHub Actions / Azure DevOps)

When running `Expert`, `Teammate`, or `TestCasesGenerator` from CI/CD, pass `--ciRunUrl` to link every ticket comment to the pipeline run.

**The workflow `ai-teammate.yml` does this automatically** — no extra config needed. For other pipelines:

```bash
# GitHub Actions
CI_RUN_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
dmtools run agents/teammate.json --ciRunUrl "${CI_RUN_URL}"

# Azure DevOps
CI_RUN_URL="$(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)"
dmtools run agents/teammate.json --ciRunUrl "${CI_RUN_URL}"
```

**What happens on the ticket**:
1. `Processing started. CI Run: https://...` — posted immediately when the job picks up the ticket
2. Normal result comment posted when job finishes

**CLI overrides** — any `--key value` after the config file patches the `params` block:
```bash
# Override any param at runtime without editing the JSON
dmtools run agents/config.json "${ENCODED_CONFIG}" --inputJql "key=PROJ-42" --ciRunUrl "${CI_RUN_URL}"
```

See [CI Run Tracing](references/jobs/README.md#ci-run-tracing) and [GitHub Actions](references/workflows/github-actions-teammate.md) for full details.

### Integrate CLI Agents (Cursor, Claude, Copilot)

**Use Case**: Code generation with full workspace context

```json
{
  "name": "Teammate",
  "params": {
    "agentParams": {
      "aiRole": "Senior Software Engineer",
      "instructions": ["Implement ticket from input/ folder"]
    },
    "cliCommands": [
      "./cicd/scripts/run-cursor-agent.sh \"Read from input/, write to output/\""
    ],
    "skipAIProcessing": true,
    "postJSAction": "agents/js/developTicketAndCreatePR.js",
    "inputJql": "key = PROJ-123"
  }
}
```

**Pattern**: Teammate prepares context → CLI agent processes → Post-action creates PR

See [CLI Integration Guide](references/agents/cli-integration.md) for complete examples.

## Best Practices

1. **Security**: Never commit credentials - use environment variables
2. **AI Provider**: Start with Gemini (free tier, 15 req/min)
3. **Testing**: Mock external APIs with Mockito
4. **Batch Processing**: Add delays to avoid rate limits
5. **Error Handling**: Always use try-catch in agents

## Troubleshooting Quick Reference

| Issue | Solution |
|-------|----------|
| "Java 17+ required" | Run installer again, it auto-installs Java |
| "401 Unauthorized" | Check base64 encoding of Jira credentials |
| "Rate limit exceeded" | Add `sleep(1000)` between API calls |
| "Field not found" | Use `jira_get_fields` to find custom field IDs |

## Architecture Notes

- **Job System**: 20+ specialized jobs for workflows
- **Agent System**: Java and JavaScript agents for AI tasks
- **Configuration**: Hierarchy - env vars > dmtools.env > dmtools-local.env
- **Thread Safety**: JobContext with thread-local storage
- **DI Framework**: Dagger 2 for dependency injection

## Resources

- Repository: https://github.com/epam/dm.ai
- MCP Tools Reference: https://github.com/epam/dm.ai/tree/main/dmtools-ai-docs/references/mcp-tools
- Issues: https://github.com/epam/dm.ai/issues

## 🤖 AI Assistant Instructions

### When to Trigger Setup Automatically

**ALWAYS run setup checks when user:**
- Mentions "dmtools" for the first time in conversation
- Asks to use any DMtools feature (Jira, test generation, etc.)
- Gets an error like "dmtools: command not found"
- Asks "how do I install dmtools"

### Proactive Setup Pattern

```markdown
I see you want to use DMtools. Let me check if it's set up properly...

[Run setup checks]

Results:
- ✓ DMtools installed
- ✗ dmtools.env not found
- ✗ Not in .gitignore

I'll help you configure it. First, which integrations do you need?
1. Jira
2. Azure DevOps
3. Both
4. Other

[Create appropriate dmtools.env template]
[Add to .gitignore]
[Guide user to get API tokens]
```

### Example: Automated Setup Flow

```bash
# Step 1: Install or update DMtools
curl -fsSL https://github.com/epam/dm.ai/releases/latest/download/install.sh | bash

# Step 2: If dmtools.env needs credentials, guide user:
# "I've created dmtools.env. You need to add your credentials:
#  1. Jira API token: https://id.atlassian.com/manage-profile/security/api-tokens
#  2. Gemini API key (FREE): https://aistudio.google.com/app/apikey
#
#  Would you like me to help you configure Jira or Gemini first?"

# Step 3: Help user edit dmtools.env
# Step 4: Test with: dmtools list
```

### Configuration Templates

Keep these handy for quick setup:

**Jira Only:**
```bash
JIRA_BASE_PATH=https://company.atlassian.net
JIRA_EMAIL=user@company.com
JIRA_API_TOKEN=token_here
JIRA_AUTH_TYPE=Basic
GEMINI_API_KEY=key_here
DEFAULT_LLM=gemini
DEFAULT_TRACKER=jira
```

**Azure DevOps Only:**
```bash
ADO_BASE_PATH=https://dev.azure.com/org
ADO_PAT_TOKEN=token_here
GEMINI_API_KEY=key_here
DEFAULT_LLM=gemini
DEFAULT_TRACKER=ado
```

**Both Jira + ADO:**
```bash
JIRA_BASE_PATH=https://company.atlassian.net
JIRA_EMAIL=user@company.com
JIRA_API_TOKEN=jira_token
JIRA_AUTH_TYPE=Basic
ADO_BASE_PATH=https://dev.azure.com/org
ADO_PAT_TOKEN=ado_token
GEMINI_API_KEY=key_here
DEFAULT_LLM=gemini
DEFAULT_TRACKER=jira
```

## Ask Questions

If you need clarification on requirements or implementation details, ask the user for more information before proceeding.