ATLAS customization guide

ATLAS is split so users can change public behavior without touching runtime controllers whenever possible.

Use this rule of thumb:

• edit Markdown when you want different model-facing wording;
• edit JSON when you want different declarative policy or defaults;
• edit Python only when you want different control flow, validation, storage, or integration behavior.

Safe customization map

Goal	Edit
Change checkpoint reflection wording	atlas_runtime/assets/checkpoint_reflection.md
Change final-gate protocol	atlas_runtime/assets/pre_submission_protocol.md and, for Claude Code, atlas_integration/claude_code/assets/final_gate_tail.md
Change Claude Code standing instruction	atlas_integration/claude_code/assets/standing_prompt.md
Change single-LLM standing instruction	atlas_integration/single_llm/assets/standing_prompt.md
Change simple judge prompts	judge_types/assets/
Change Reflection Judge staged prompts	judge_types/reflection_judge/assets/
Change refinement prompt wording	atlas_runtime/assets/standard_refinement_prompt.md, reflection_refiner_system.md, reflection_refiner_user.md, refinement_support_judge.md, refinement_repair.md
Change taxonomy-generation prompt wording	vendor/atlas/pipeline/assets/
Change classifier prompt wording	vendor/atlas/assets/classifier_system.md, classifier_user.md
Change recognized model context profiles	atlas_runtime/assets/model_profiles.json
Change Claude Code event lists	atlas_integration/claude_code/assets/hook_events.json
Change Reflection Judge schema enums	judge_types/reflection_judge/assets/schema_enums.json
Change generation seed role definitions	vendor/atlas/pipeline/assets/role_definitions.json
Change checker keyword lists	vendor/atlas/pipeline/assets/checker_terms.json
Change config-file validation	atlas_runtime/assets/atlas_config.schema.json plus Python config loaders

Config file first

For most deployments, prefer an atlas.json checked into the project rather than long command lines:

{
  "version": 1,
  "trace_output": "./atlas-program",
  "atlas_model": "gpt-5",
  "generation_threshold": 5,
  "generation_stops": false,
  "k_init": 10,
  "k": 20,
  "freeze": false,
  "claude_code": {
    "built_in_hooks": {
      "SubagentStop": false,
      "PostToolUse": {
        "enabled": true,
        "matchers": ["Bash", "Edit", "Write"]
      },
      "PostToolUseFailure": ["Bash"]
    }
  }
}

Explicit CLI flags override config values. Unknown config fields are rejected so misspellings do not silently change behavior.

Hook customization

Claude Code has two hook layers:

1. built-in hooks, configured with claude_code.built_in_hooks;
2. custom hooks, configured with atlas-claude-add-hook or the claude_code.custom_hooks array in atlas.json.

Built-in hook policy belongs in project config:

{
  "claude_code": {
    "built_in_hooks": {
      "SubagentStop": false,
      "PostToolUse": ["Bash", "Edit", "Write"],
      "PostToolUseFailure": {
        "enabled": true,
        "matchers": ["Bash"]
      }
    }
  }
}

Custom hooks are for additional events:

atlas-claude-add-hook \
  --project-dir . \
  --name pre-bash \
  --event PreToolUse \
  --matcher Bash \
  --command-pattern "python .*eval" \
  --checkpoint-key fixed \
  --mode blocking

Use blocking when the agent must satisfy the reflection contract before continuing. Use advisory when the agent should receive a nudge but the host should not block.

matcher is the host tool/event matcher, usually tool-name granularity such as Bash. command_pattern is an optional regex against tool_input / command text, so one Bash hook can fire only for a recurring command. Use checkpoint_key to control how repeated firings close:

Value	Use
tool_use_id	Default; each host tool call is independent.
command	Same command text shares a checkpoint key.
fixed	The hook name has one stable in-flight checkpoint.

Taxonomy customization

A taxonomy record is selected only by taxonomy_id.

{
  "taxonomy_id": "my-taxonomy-v1",
  "repo": "display-only",
  "domain": "display-only",
  "codes": [
    {
      "id": "C-1",
      "name": "Observable failure name",
      "description": "Task-neutral diagnostic definition.",
      "category": "Custom"
    }
  ]
}

Register an existing taxonomy:

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

Use it:

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

repo and domain are display metadata. They do not route, group, or select taxonomies.

What not to customize lightly

These Python modules are deliberately behavioral:

Area	Why it should stay Python
atlas_runtime/lifecycle.py	owns session boundaries and generation/refinement trigger timing
atlas_runtime/program.py	owns lock-coordinated program state and pending traces
atlas_runtime/traces.py	owns canonical trace persistence and integration into taxonomy trace folders
atlas_runtime/reflection.py	parses the reflection contract from model text
atlas_runtime/protocol.py	validates final-gate shape and retry envelope
judge_types/*/schema.py, validators, and controllers	enforce output structure after model calls
atlas_integration/*/runtime.py	adapts host events to runtime calls

If you change these, run the full test suite.

Verification after customization

Run at least:

python -m compileall atlas_runtime atlas_integration finding judge_types vendor
python -m pytest -q
git diff --check

For packaging-sensitive changes to assets:

python -m pip wheel . --no-deps -w dist-check

Then inspect the wheel and confirm your new asset files are included.