dart playbook

dart-playbook · Sequencing rules in YAML

The agent's playbook. A YAML file that encodes "what should a senior analyst look at next, given the current state of the case?" — without writing imperative Python.

---

Why YAML, not Python

The whole point of architecture-first, not prompt-first is that operator-tunable rules don't live in the model's prompt. They live in YAML the operator can read and edit.

A Python playbook would couple the rules to the agent's release cycle. A YAML playbook is data: an analyst can fork the playbook, tune for their specific case class (web-app breach vs insider threat vs ransomware), and commit it to their own runbook repo.

---

Anatomy of senior-analyst-v1.yaml

case_class: insider_threat_remote_hands

initial_hypothesis: |
  An authorized user with legitimate credentials has used an out-of-band
  channel (IP-KVM, console, USB) to access systems outside their normal
  pattern. Need: process tree, USB history, login records.

next_call_decisions:
  - when_state: "no process tree yet"
    call: get_process_tree
    confidence_gain: 0.10

  - when_state: "no USB history yet AND case_class includes physical access"
    call: analyze_usb_history
    confidence_gain: 0.20

  - when_state: "credential dump suspected AND no detect_credential_access yet"
    call: detect_credential_access
    confidence_gain: 0.25

contradiction_triggers:
  - source_a: auth_events
    source_b: mft_timestomp
    threshold_seconds: 30
    rule: "If timestomp ts < auth ts, persistence pre-existed credential use"

stop_conditions:
  - confidence >= 0.90
  - iterations >= 25
  - no_new_calls_possible

The agent reads this at startup. Each iteration, it queries the YAML to decide the next move. The deterministic-mode policy is essentially "execute this YAML"; the live mode lets the model deviate, but every call still goes through the typed dart-mcp surface.

---

Bundled playbooks

File	Case class
senior-analyst-v1.yaml	Insider threat / remote-hands (the IP-KVM bundled case)

Phase 2 will add:

• coverage-gap-analyst-v1.yaml — for detection-engineering work (different reasoning, same surface)

---

Writing your own playbook

1. Copy senior-analyst-v1.yaml to <your-name>-v1.yaml
2. Edit case_class, initial_hypothesis, next_call_decisions
3. Run with --playbook <your-name>-v1.yaml
4. The agent will follow your sequencing while the architecture (read-only, audit-chained, contradiction-aware) is unchanged.

A playbook cannot loosen architectural guarantees. It can only choose what to call from the surface, never expand the surface.

---

Files

dart_playbook/
├── README.md
└── senior-analyst-v1.yaml

---

See also

• dart-agent — how the playbook gets executed
• Architecture deep dive
• dart_playbook/senior-analyst-v1.yaml — the actual file