Quick Start

Get dmx running in a project in under 10 minutes.

PrerequisitesCopy Anchor Link

• Python 3.11 or later
• uv installed (provides uvx) — dmx runs via uvx, so there's nothing to install globally
• An agentic IDE: Cursor, Claude Code, VS Code with GitHub Copilot, or any MCP-compatible IDE
• A GitHub repository cloned locally, with an origin remote. The Spec Loop creates feature branches on GitHub, even if you track work in Jira or use no ticketing system.
• The GitHub MCP server (user-github) connected and authenticated in your IDE. /dmx/init checks for it before writing any files.
• The Atlassian MCP server, only if you'll use Jira for tickets

Step 1: Connect your IDECopy Anchor Link

dmx runs as an MCP server. You need to tell your IDE where to find it.

Every IDE uses the same config:

{
  "mcpServers": {
    "dmx": {
      "command": "uvx",
      "args": ["--from", "deepmodel-dmx@latest", "dmx", "serve"]
    }
  }
}

Save it to the file for your IDE:

Restart your IDE after saving. See MCP Setup for the Claude Code CLI across all projects, Windows paths, and other IDEs. Rolling dmx out with Jamf or Intune is covered in Enterprise Deployment.

Step 2: Initialize your projectCopy Anchor Link

On your integration branch (main or master), run:

/dmx/init

This command walks you through a one-time setup:

1. Workflow mode: sdlc (the structured lifecycle this guide follows) or freestyle (no process enforced)
2. Ticketing system: Jira, GitHub Issues, or none
3. Branching strategy: integration branch, production branch
4. Tech stack auto-detection: reads your pyproject.toml, package.json, or Cargo.toml
5. Scaffolds .dmx/: creates the memory bank with your project context

The .dmx/ directory is committed to your repo. Every developer on your team gets the same project context automatically.

Open a new chat in your IDE once init finishes, so the rules it wrote take effect.

Step 3: Commit and pushCopy Anchor Link

The Spec Loop must start from your integration branch, and it creates the new feature branch from what's already on origin. Commit what init wrote and push it before you start:

git add .dmx/
git commit -m "chore: initialize dmx memory bank"
git push -u origin HEAD

Init also writes rule files for your IDE, such as .cursor/rules/ or a dmx block in CLAUDE.md. Commit those too if your team shares them. Stay on your integration branch.

On a brand-new repository with no commits, the Spec Loop stops with an error telling you to do this first.

Step 4: Run your first Spec LoopCopy Anchor Link

Start it directly with a short description of the work:

/dmx/run-loop spec

Add rate limiting to the public inference endpoint.

The loop's one skill, create-ticket, uses that description to scaffold the ticket, branch, and spec.

dmx will:

1. Create a ticket in your configured ticketing system (skipped when ticketing is none)
2. Create a branch from origin/{branch_base} and check it out
3. Scaffold a spec.md pre-filled with your project context, including a Q&A section
4. Pause for your review — this is the human gate

Answer the Q&A directly in spec.md, then resume the loop:

/dmx/loop-continue

This is what actually triggers the Spec Loop validator (check_spec_complete), which checks that:

• spec.md exists and is non-empty
• All Q&A questions have answers (not just "TBD")
• The Technical Approach section is filled in
• The Scope section is defined
• The spec belongs to the branch you're on

If all checks pass, dmx automatically chains to the Plan Loop.

Step 5: Approve the planCopy Anchor Link

The Plan Loop starts automatically as soon as the Spec Loop succeeds. It runs the plan skill, which reads your spec.md and generates a phased tasks.md, then pauses for your review — the human gate.

Review tasks.md. When it looks right, resume:

/dmx/loop-continue

dmx validates tasks.md, then chains to the Dev Loop.

Step 6: BuildCopy Anchor Link

The Dev Loop runs /dmx/implement-next-phase. It executes every task in the first unchecked phase of tasks.md, checks each one off as it completes, and then stops.

Each phase pauses twice:

1. After implement-next-phase. Review the diff, then continue:

   Copy Text

   /dmx/loop-continue

   This runs commit, which commits the phase. It doesn't push.

2. After commit. Review the commit, then continue again:

   Copy Text

   /dmx/loop-continue

   If phases remain, the next one starts. Once every phase is checked off, the test suite runs and the loop chains to the Validate Loop.

Step 7: Validate and open the PRCopy Anchor Link

The Validate Loop runs the validate skill, a quality gate covering ticket completeness, code quality, and security, then pauses. Review the report. If it says NEEDS WORK, address the findings first. Then:

/dmx/loop-continue

On success, dmx chains to the Release Loop, which runs create-pr: it syncs the memory bank, pushes the branch, opens the pull request, and transitions the ticket to In Review. It pauses once more so you can check the PR; continue to run the final check_pr_ready validator:

/dmx/loop-continue

Step 8: Merge and closeCopy Anchor Link

Review and merge the PR as you normally would. Then close out the ticket:

/dmx/close-ticket

This transitions the ticket to Done, comments the PR link on it, and deletes the feature branch locally and on origin. The Release Loop ends when the PR exists, so /dmx/loop-continue after the merge isn't a way to close the ticket.

What just happenedCopy Anchor Link

You just ran a complete AI SDLC workflow:

• Every phase had a human gate. The AI stopped and waited for your approval before proceeding.
• Validators ran automatically at every loop boundary, and blocked progress when a required check failed.
• Job state was persisted in .dmx/. Close your IDE and resume tomorrow.

You can also run each step by hand instead of through loops: /dmx/create-ticket, /dmx/plan, /dmx/implement-next-phase, and so on. See the Command Reference.

Next stepsCopy Anchor Link

• Read Core Concepts: Loops to understand how loops work
• See The Default Loops for a detailed walkthrough of each loop
• Learn about Validators to understand what's being checked
• Explore Loop Configuration to customize loops for your project