SpandrelA framework that turns markdown file trees into governed knowledge graphs — philosophy, spec, and reference implementation

Paths

Five entry points matched to user starting materials — different inventory rules and seeding steps for empty, bulk, survey, existing, or code starts. One linear flow would force inappropriate prompts.

Paths

Users arrive at onboarding with very different starting materials. One linear flow forces inappropriate prompts. Five paths, each with its own inventory rules, sense-making style, seeding steps, and gotchas.

The five paths

  • empty — nothing yet. Purpose from Level 0, no existing content. Template selection drives structure.
  • bulk — an unstructured pile the user wants to process in this conversation. Shape emerges from dialogue, not filesystem scans.
  • survey — an existing directory with some shape. Agent inventories before proposing.
  • existing — a curated corpus or an already-Spandrel repo. Audit mode: don't re-propose structure, edit in place.
  • code — a code repo to document. Source files stay out; manifests, READMEs, and ADRs seed the graph.

How to pick

Level 1 of ONBOARDING.md asks the user to list every source upfront, then classifies each source into a path. Most sessions land on a single path. When multiple sources span paths (e.g. a code repo plus a directory of exported notes), the primary path is the one with the most signal; others get layered via the seeding steps of the primary path.

Rubric

Every path file has the same five sections so they're comparable. The rubric an author uses when adding a new path lives in this collection's DESIGN.md companion file.