The big idea: outcomes over answers

In classic assistants you ask a question and get a reply. With intent‑oriented systems you ask for a result— “correlate weak RSRP with complaints, suggest tilt changes, produce a change plan, then monitor impact”—and the system coordinates tools, data, and steps to deliver it. That shift is the heart of DOIL.

What DOIL is

• A Ruby‑inspired, Git‑native language for describing operational intent.
• One language, three compile targets: a runtime agent, a simulator scenario, or a cockpit panel — same intent, different target flag.
• Vendor‑neutral codegen with rollback markers; the compiler (doilgen), wizard (builddoil), VSCode extension, and test environment all ship in the open repo.
• Designed to capture expert playbooks so they run consistently against the Reality Twin.

Start with the framing:The Reality Twin

How it feels to use (NOC/telecom)

You write down the outcome you want; DOIL figures out the tool calls, data sources, and UI to make it happen. Less swivel‑chair work, fewer dropped handoffs, clearer workflows.

From intent to system: how DOIL flows

You begin with a short back‑and‑forth with the DOIL agent to clarify your intent (outcomes, guardrails, data, and actions). The agent then drafts a readable .doil file that captures that intent. You review and edit the file until it precisely reflects what you want.

Only after that review does compilation start: the system validates bindings, prepares assistant contexts, and generates a small UI so you can see inputs, results, and live status. The .doil file can be shared, discussed with other engineers, versioned in Git, and integrated with other files and systems.

A day‑in‑the‑life: NOC escalation

Morning alerts flag pockets of poor RSRP. You declare: “Correlate weak signal sectors with last‑24h complaints, propose neighbor/tilt adjustments, build a minimal change plan, and set up a live view to watch impact after deployment.” DOIL assembles the steps: fetch coverage metrics, join with ticket volumes, apply heuristics for tilt/neighbor tweaks, produce a checklist, and spin up a monitoring map. You review, approve, and the plan runs. Later, the same file becomes your team’s shared playbook.

Anatomy of a .doil file

• Triggers: when it runs (schedule/events)
• Data sources: metrics/APIs/files to read
• Tools: actions the system can take (notify, analyze, change configs)
• Intent/logic: the high‑level plan tying it together

Example .doil (NetworkCoverageOps)

agent NetworkCoverageOps
  intent 'Correlate weak RSRP with complaints, propose tilt/neighbor fixes, and monitor impact'

  mcp_binding :coverage_data, 'coverage-mcp' do
    tools [:get_coverage_metrics, :analyze_coverage]
    resources [:coverage_maps, :coverage_metrics]
  end

  mcp_binding :tickets_data, 'tmf717-customer360' do
    tools [:get_recent_tickets]
    resources [:tickets]
  end

  orchestrate :claude_code do
    context 'RF engineer analyzing weak-signal sectors'
    tools [mcp_binding(:coverage_data), mcp_binding(:tickets_data)]
    workflow 'correlate → analyze → recommend'
  end

  orchestrate :cursor do
    context 'Config generator for tilt/neighbor adjustments'
    tools [mcp_binding(:coverage_data)]
    workflow 'generate → validate'
  end

  workflow improve_coverage do
    step :correlate_hotspots do
      tools [mcp_binding(:coverage_data), mcp_binding(:tickets_data)]
      input :last_24h
      output :hotspots
    end

    step :recommend_changes do
      agent :claude_code
      input :hotspots
      output :change_plan
    end

    step :generate_configs do
      agent :cursor
      input :change_plan
      output :config_snippets
    end
  end

  ui_dashboard :noc_coverage_watch do
    data_sources [
      mcp_binding(:coverage_data).get_coverage_metrics(),
      mcp_binding(:tickets_data).get_recent_tickets()
    ]

    widget :coverage_heatmap do
      type :geospatial_map
      layers ['coverage_areas', 'tickets_density']
      refresh_interval 30
    end

    widget :kpis do
      type :line_chart
      metrics ['rsrp_poor_cells', 'ticket_volume']
    end
  end
end

How this is processed

1. Conversational planning: clarify intent with the DOIL agent; capture outcomes and constraints.
2. Draft .doil: agent generates a first pass; you edit it to match your exact needs.
3. Parse & validate: DOIL file → AST (lexer/parser), syntax and reference checks.
4. Discover MCP: Registry loads your MCP config, verifies servers, tools, resources.
5. Prepare contexts: Build assistant‑specific context for claude_code and cursor.
6. Plan orchestration: Compile the workflow into an execution graph (typed I/O).
7. Generate UI: Create React dashboard + data connectors (WebSocket streaming).
8. Run & iterate: Preview, execute, and refine; share the .doil with your team.

Related reads

• The Reality Twin (start here) —darknoc.dev
• The simulator cascade —darknoc.dev
• The open registry (44 agents, 10 simulators) —darknoc.org
• Introducing DOIL (intent‑first perspective) —darknoc.dev