Skip to main content
On this page

Project-scoped overrides

adk reads three project-scoped locations whenever a skill runs inside a repo.

Priority order

When a skill resolves a config value, it merges in this order (later wins):

  1. $ADK_CONFIG_HOME/overrides.yaml (user-level, lowest priority)
  2. <repo>/.adk/overrides.yaml (repo-level)
  3. CLI flags or explicit args (highest priority)

<repo>/.adk/overrides.yaml

Narrow overrides for the current repo. Useful when the repo has conventions that differ from your user-level defaults.

Example — a repo that uses Jest despite your global default of Vitest:

YAML
# <repo>/.adk/overrides.yamldefaults:  adk-implement:    test-framework: jest    pr-strategy: split-by-area     # this repo is large; default to multi-PR splits  adk-review:    severity-bar: blocker+critical-only

The team can choose to commit this file (so the repo has consistent adk behavior for everyone) OR keep it gitignored (per-developer).

To inspect the effective merged config, use python3 scripts/config_io.py show-core (or show-connector <name> / show-links).

<repo>/ai-guidelines/ (or <repo>/docs/)

Repo-specific conventions adk reads at every skill run. Useful for things that aren’t config but are still rules — coding style, architecture decisions, banned patterns.

Text
<repo>/ai-guidelines/├── architecture.md         # how the BFF talks to downstream services├── api-conventions.md      # this repo's endpoint naming├── testing.md              # the team's preferred test patterns└── deploy.md               # deploy steps and rollback

Skills detect these and load the relevant ones based on task type (e.g., architecture.md when implementing a new service boundary; testing.md always for /adk-implement checkpoints).

<repo>/.temp/<task-slug>/

Every skill writes intermediates here. Gitignored by default (in adk’s .gitignore template).

Text
<repo>/.temp/├── implement-SF-1234/│   ├── prompt.txt              # the user's input│   ├── context.md              # Phase 0 fan-out (Jira + GH + Confluence + RAG)│   ├── plan.md                 # Phase 1 advisor output│   ├── proposal.md             # 2–4 trade-off options│   ├── steps/                  # per-checkpoint logs│   ├── diffs/applied.jsonl     # SEARCH/REPLACE blocks applied│   ├── findings/               # validator output│   ├── decision-log.jsonl      # session-scoped (also tee'd to $ADK_DATA_HOME/improve/learning/decisions.jsonl)│   └── report.md               # final├── review-pr-456/│   └── ...└── investigate-checkout-2026-05-18/    └── ...

Task-slug convention: <skill-stem>-<discriminator>, e.g., implement-SF-1234, review-pr-456, investigate-checkout-2026-05-18. Generated by scripts/adk_task_slug.py.

The .temp/ folder is the user’s session-scoped memory. Don’t gitignore-add specific files inside it; just gitignore the directory.

<repo>/.gitignore entries

Add these to any repo where you’ll use adk:

Gitignore
.temp/.adk/                  # if you keep .adk/ per-developer; remove this line to commit it

Resolution order example

Goal: figure out the effective test-framework for a run.

  1. CLI flag: /adk-implement <ticket> --test-framework jest → wins immediately.
  2. Else: <repo>/.adk/overrides.yaml.defaults.adk-implement.test-framework: jest → used.
  3. Else: $ADK_CONFIG_HOME/overrides.yaml.defaults.adk-implement.test-framework: vitest → used.
  4. Else: skill-detected from package.json / pyproject.toml / Cargo.toml.
  5. Else: skill recommends a default at advisor phase.

Next