purpose-tree

A project's purpose tree records why each part of the project exists. Implementations change often; purposes rarely do. Keeping them apart lets you replace any implementation without losing sight of what it was for.

Where the tree lives

• In the project, never in this skill: purpose-tree.yaml at the project root.
• If it is missing, look for the legacy name architecture.yaml. Read and update whichever exists; do not rename it unless asked.
• Create the file lazily: only when the human states the first (root) purpose.

Purpose, metric, realization

Each node separates three things that change at different speeds:

If a purpose names a number or target, move it to metrics. If it names a tool, file, or schedule, move it to realized_by. Then ask what it is for.

Node format (v3.0)

A purpose is realized by a list of means. A means is either a concrete implementation (a string) or a sub-purpose (an object with purpose). One list, two kinds — an item with a purpose field is a sub-purpose; anything else is an implementation.

version: "3.0"
root:
  id:            root
  purpose:       Why this exists (one sentence)
  status:        active | paused | planned   # default active; retired nodes are deleted
  status_note:   Current state, known gaps
  paused_reason: Required when paused or planned: why, and how to resume
  metrics:                                   # list of block mappings, not {...}
    - name: …
      source: …
      healthy: …
  tests:         [test file patterns]
  health_check:                              # exit 0 = healthy
    command: …
    expected: …
  realized_by:
    - scripts/capture.js                     # implementation
    - id: daily_awareness                    # sub-purpose: same node format, recursive
      purpose: Know what matters before the day starts
      realized_by:
        - morning brief job