istin/dmtools

DMtools Development Assistant

Comprehensive knowledge base for DMtools - an AI-powered development toolkit that integrates with multiple platforms and provides 96+ MCP tools for automation.

🔧 FIRST-TIME SETUP (DO THIS PROACTIVELY)

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

🚀 Quick Automated Setup (Recommended)

Run the automated setup helper that checks and configures everything:

# Download and run setup helper
curl -fsSL https://raw.githubusercontent.com/IstiN/dmtools/main/dmtools-ai-docs/setup-dmtools.sh | bash

This script will:

1. ✓ Check if DMtools is installed (and install if missing)
2. ✓ Create dmtools.env template if missing
3. ✓ Add dmtools files to .gitignore
4. ✓ Verify Java installation
5. ✓ Test DMtools functionality

OR follow manual steps below:

Step 1: Check if DMtools is installed

# Check if dmtools command is available
which dmtools || echo "DMtools not installed"

If NOT installed:

# Offer to install DMtools automatically
curl -fsSL https://raw.githubusercontent.com/IstiN/dmtools/main/install.sh | bash

Step 2: Check for dmtools.env configuration

# 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

# 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:

# DMtools configuration (contains secrets)
dmtools.env
dmtools-local.env
.dmtools/

Configuration Template

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

# 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
[email protected]
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

# 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, dmc_report)
• Troubleshooting DMtools issues
• Working with dmtools.env configuration
• Creating AI teammate configurations
• Setting up CI/CD run tracing (ciRunUrl) for ticket traceability

Quick Reference

⚠️ IMPORTANT: If this is first time using DMtools, see FIRST-TIME SETUP section above.

Manual Installation Steps

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

1. Install DMtools CLI

curl -fsSL https://raw.githubusercontent.com/IstiN/dmtools/main/install.sh | bash

2. Create dmtools.env

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

3. Add to .gitignore

echo -e "\n# DMtools configuration\ndmtools.env\ndmtools-local.env\n.dmtools/" >> .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 for detailed setup.

Common Commands

dmtools list                          # List all 96+ 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

152+ MCP Tools Available

Complete Reference: references/mcp-tools/README.md - Auto-generated from actual DMtools build

Current breakdown (16 integrations):

• Jira (52 tools): Ticket management, search, comments, Xray test management
• Teams (30 tools): Messages, chats, files, transcripts, meetings
• Confluence (17 tools): Page management, search, content access, attachments
• ADO (14 tools): Azure DevOps work items, queries, comments, attachments
• Figma (12 tools): Design extraction, icons, layers, styles, components
• AI Providers (12 tools):
  • Gemini (2): Chat, multimodal
  • OpenAI (2): Chat, vision models with files
  • Anthropic (2): Claude chat
  • Bedrock (2): AWS Claude
  • DIAL (2): Enterprise AI
  • Ollama (2): Local models
• 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
• 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
• 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:

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 | Complete setup for all platforms (macOS, Linux, Windows) | | | Troubleshooting | Common issues and solutions | | Configuration | Configuration Overview | Environment variables and hierarchy | | | JSON Configuration Rules | ⚠️ CRITICAL: Rules for job configurations | | | Jira Setup | API tokens and 52 tools | | | Azure DevOps | PAT setup and 23+ tools | | | Gemini AI | Free tier configuration (15 req/min) | | | Other AI Providers | OpenAI, Claude, DIAL, Ollama | | Jobs | Jobs Reference | Complete guide to all 23 jobs | | | Teammate | Flexible AI assistant with custom instructions | | | Expert | Domain expert Q&A based on project context | | | TestCasesGenerator | Automated test case generation | | | ReportGenerator | Report configuration, data sources, metrics | | Agents | Agent Best Practices | ⚠️ CRITICAL: Patterns and lessons learned | | | JavaScript Agents | GraalJS development with 152+ MCP tools | | | Teammate Configs | JSON-based AI workflows (CLI safety v1.7.133+) | | | CLI Integration | Cursor, Claude, Copilot, Gemini CLI agents | | Testing | Test Generation | Xray test case creation | | MCP Tools | MCP Tools Reference | Auto-generated list of 152+ tools (16 integrations) | | CI/CD | GitHub Actions | 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).

{
  "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 for details.

---

Common Tasks

Configure Jira Integration

# 1. Generate API token at https://id.atlassian.com/manage-profile/security/api-tokens
# 2. Encode credentials
echo -n "[email protected]: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.

{
  "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

// 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:

# 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:

# 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 and GitHub Actions for full details.

Integrate CLI Agents (Cursor, Claude, Copilot)

Use Case: Code generation with full workspace context

{
  "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 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 23 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/IstiN/dmtools
• MCP Tools Reference: https://github.com/IstiN/dmtools/blob/main/docs/README-MCP.md
• Issues: https://github.com/IstiN/dmtools/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

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

# Step 1: Run automated setup
curl -fsSL https://raw.githubusercontent.com/IstiN/dmtools/main/dmtools-ai-docs/setup-dmtools.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:

JIRA_BASE_PATH=https://company.atlassian.net
[email protected]
JIRA_API_TOKEN=token_here
JIRA_AUTH_TYPE=Basic
GEMINI_API_KEY=key_here
DEFAULT_LLM=gemini
DEFAULT_TRACKER=jira

Azure DevOps Only:

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:

JIRA_BASE_PATH=https://company.atlassian.net
[email protected]
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.