Skip to content

Taxonomies

This page shows how stored taxonomies are identified, reused across runs, registered by hand, and related to each other over time.

Two rules drive everything below:

  • A taxonomy is selected by one immutable key, taxonomy_id. It never changes for a stored taxonomy.
  • display_name, repo, domain, and summary are user-facing metadata only. They never route, group, or select taxonomies, so changing display_name changes what people see without breaking stored traces or lineage references.

Run this first

Commands on this page read the bundled examples. Create them in the directory you are working from with python -m adamast.examples.

📄 Record shape

{
  "taxonomy_id": "my-taxonomy-v1",
  "display_name": "Checkout Workflow Reliability",
  "repo": "display-only",
  "domain": "display-only",
  "summary": "Failure modes affecting checkout implementation and verification.",
  "codes": [
    {
      "id": "C-1",
      "name": "Observable failure name",
      "description": "Task-neutral diagnostic definition.",
      "category": "Custom"
    }
  ]
}

The store is flat: one JSON file per taxonomy, named <taxonomy_id>.json.

🧭 Built-in MAST

If a run starts without inheritance, Finding returns none and the runtime resolves that to the built-in MAST constant.

Note

MAST is not a store record and does not appear in store.list_all. Codex and Claude Code selectors still offer it explicitly as the built-in starting taxonomy. The standalone adamast find --inherit-pick command lists stored records rather than host-specific built-ins.

🎯 Inherit a taxonomy

To start a run from a taxonomy you already trust:

  1. Browse what is stored with the interactive picker:

    adamast find --inherit-pick

    The searchable picker shows human-readable names, summaries, source projects, code counts, and immutable IDs as secondary metadata. Clicking a row opens the full taxonomy content.

  2. Or pass the ID directly, non-interactively:

    adamast single-run --config adamast.json --inherit my-taxonomy-v1 --model gpt-5 --task "..."

Opting out

Choosing Start without a stored taxonomy returns none in the standalone blocking CLI flow. In a Codex or Claude Code selector, No taxonomy disables AdaMAST only for that conversation.

📝 Register a taxonomy

To store a taxonomy file you prepared yourself:

adamast register-taxonomy --file taxonomy.json --id my-taxonomy-v1

📥 Import existing traces

Generate and store an inheritable taxonomy from traces you already have:

adamast import-traces \
  --config adamast.json \
  --traces adamast-examples/traces.jsonl

Imported taxonomies become normal flat store records after acceptance. If you need a specific ID, register a prepared taxonomy with adamast register-taxonomy --id ....

🌳 Lineage

Generated and refined taxonomies get new taxonomy IDs. Refinement records a parent-to-child edge from the exact version used by that conversation branch. One parent may have several children when conversations evolve independently; each branch manifest records its own head, so no child is treated as the global latest taxonomy after a split.

➡️ Continue with