dmtools

# DMtools Development Assistant DMTools is an enterprise dark-factory orchestrator that integrates with multiple platforms and provides 373+ 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 373+ 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 ### 373+ 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** (77 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 373+ 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 |