Plan -> Work -> Evidence

Plan -> Work -> Evidence is the public mdkg workflow.

Plan the goal. Execute one work node. Record evidence. Validate before moving on.

Plan Define the goal, scope, context, checks, and stop conditions.

Work Claim one executable task, test, bug, or spike.

Evidence Record checkpoints, receipts, packs, and handoff summaries.

Validate Run checks, fix issues, and route the next node.

Plan

Planning nodes capture durable intent before an agent starts editing:

goals
epics
product requirements
engineering designs
decisions
rules

These nodes explain what matters, why it matters, and which boundaries should not be crossed.

Minimal goal frontmatter:

---
id: goal-1
type: goal
title: Complete release validation
status: todo
priority: 1
goal_state: active
active_node: task-1
scope_refs:
  - task-1
  - test-1
context_refs:
  - dec-1
required_checks:
  - npm run test
  - mdkg validate
---

Work

Work nodes are the units humans and agents can act on:

features
tasks
bugs
tests
research spikes

Use mdkg goal next to select one scoped work item and mdkg pack WORK_ID to build bounded context for it.

Minimal task frontmatter:

---
id: task-1
type: task
title: Run release validation
status: todo
priority: 1
parent: goal-1
blocked_by: []
context_refs:
  - prd-1
evidence_refs: []
---

Evidence

Evidence records why the current state is safe to continue from:

checkpoints
receipts
archive sidecars
validation output
handoff summaries

Good evidence includes commands run, pass/fail state, known warnings, boundaries, and follow-up refs.

Validate

Validation closes the loop:

mdkg validate
mdkg doctor --strict --json

mdkg does not run goal checks automatically. A human or agent runs the required checks, records the evidence, and then routes the next node.

Common mistakes

Treating scope_refs as a reading list. Scope is the executable queue; use context_refs for plans and evidence_refs for proof.
Claiming a node before reading the pack. Read first, claim only when accepting the work.
Marking work done before running the required checks. Close with evidence after validation.
Storing raw prompts, tokens, provider payloads, or bulky logs in Markdown nodes. Summarize and link to safe evidence refs.