Spec Loop

The Spec Loop is the entry point for every piece of work. It takes a task description, creates a ticket and branch, and produces a complete spec before any code is written.

What it doesCopy Anchor Link

1. Creates a ticket in your configured ticketing system (Jira, GitHub Issues, or a local .dmx/ ticket)
2. Creates a branch with the correct naming convention
3. Scaffolds spec.md pre-filled with project context from the memory bank
4. Asks clarifying questions in the Q&A section of the spec
5. Waits for you to answer them
6. Validates completeness before the Plan Loop starts

How to start itCopy Anchor Link

Start the loop directly with your task description, from your integration branch (main by default):

/dmx/run-loop spec

your task description here

This runs the loop's one skill, create-ticket, which creates the ticket, branch, and spec from that description, then pauses for review.

The task description goes to the loop, not to a separate create-ticket command — running /dmx/create-ticket manually beforehand would create a second, duplicate ticket when the loop then runs create-ticket itself.

Must start from the integration branchCopy Anchor Link

The Spec Loop establishes a brand-new ticket and branch, so it only starts from the branch configured as branch_base in .dmx/config.md (typically main). If you try to run it from an existing feature branch, it's rejected with a message telling you to switch back first:

Cannot start the `spec` loop from `feature/DM-42-old-work` — it must be started
from `main` (the configured integration branch), since this loop establishes a
new ticket and branch. Switch back with `git checkout main` and run `run_loop` again.

This also means a leftover spec.md from a previously merged ticket (close-ticket doesn't delete it) is never mistaken for the new ticket's identity — the loop only adopts it once create-ticket has actually run.

Needs at least one pushed commitCopy Anchor Link

create-ticket creates the feature branch on GitHub from origin/{branch_base}, so that branch has to exist on origin with at least one commit. On a freshly initialized repository with no commits, the loop is rejected before anything is created:

Cannot start the `spec` loop: this repository has no commits yet. `spec` creates a
new branch from `main` on GitHub, which requires at least one commit to exist first.
Commit something (e.g. the `.dmx/` files `/dmx/init` just wrote) and push to origin,
then try again.

Running /dmx/create-ticket by hand does the same check and stops with a similar message.

The human gateCopy Anchor Link

After create-ticket runs and the spec is scaffolded, the loop pauses. You fill in the spec: answer the Q&A, complete the Technical Approach section, define the Scope.

When you're ready:

/dmx/loop-continue

The Spec Loop validator runs. If it passes, the loop chains to the Plan Loop.

Validator: check_spec_completeCopy Anchor Link

Five required checks:

If any check fails, the loop pauses and names each failed check with the reason. Fix the spec and run /dmx/loop-continue to retry.

spec_identity_matches_branch catches a spec.md that still belongs to another ticket, for example one left behind on your integration branch by the last merged PR. Without it, the next loops could run against the old spec.

Loop configCopy Anchor Link

name: spec
skills:
  - create-ticket
trigger:
  type: manual
require_branch: base
goal_state: "Ticket created, branch checked out, spec.md complete with all Q&A answered"
validators:
  - tool: check_spec_complete
    checks:
      - name: spec_exists
        required: true
      - name: qa_answered
        required: true
      - name: technical_approach_filled
        required: true
      - name: scope_defined
        required: true
      - name: spec_identity_matches_branch
        required: true
on_optional_failure: warn
failure_handling: pause
human_gate: true
on_complete:
  on_success:
    trigger_loop: plan

Starting from uncommitted workCopy Anchor Link

If you've already started working before creating a ticket, use /dmx/derive-ticket instead:

/dmx/derive-ticket

This reads your uncommitted changes, infers what you're building, creates a ticket retroactively, names the branch correctly, and scaffolds a derived spec.

TipsCopy Anchor Link

Write a good task description. The create-ticket skill uses it to infer ticket type, generate the branch name, and pre-fill spec sections. A specific description produces a better spec to work from.

Don't rush the Q&A. The spec Q&A is where ambiguity gets surfaced. Answer the questions even when they seem obvious. The answers become context for every subsequent loop.

The Technical Approach and Scope sections matter. The validate skill and the spec adherence check in the Validate Loop grade the change against the spec. A vague spec produces a vague check.